Miscellaneous / Testing
☰

Testing

The Toolkit has several thousand unit tests, and in the course of writing these we've developed a set of useful methods that enable us to write tests at a reasonably high level - things like "drag an edge from node '1' to node '3'", for instance, are achieved directly through the test API.

From release 2.1.0 these helper methods are shipped in jsplumbtoolkit-testing.tgz. As these have not yet been used in the wild we're interested in any feedback or suggestions licensees may have.

Setup

How you set things up for testing depends on the internals of your project, both the app itself and the testing framework you're using. The Toolkit's testing package is framework agnostic, though, and can work in any setup.

package.json

"devDependencies":{
    ...
    "jsplumbtoolkit-testing":"file:/path/to/jsplumbtoolkit-testing.tgz"
    ...
}

Script import

<script type="text/javascript" src="node_modules/jsplumbtoolkit-testing/dist/js/plumbtoolkit-testing.js"></script>

The test support exposes jsPlumbToolkitTestSupport object on the window, with two methods:

create(toolkitParams, surfaceParams?, containerParams?): jsPlumbToolkitTestHarness

We use this method internally - it creates a Toolkit and then, if surfaceParams are provided, renders it to an element that it creates.

clear()

Resets the test manager. You should run this after each of your tests.

attachToSurface(surface:Surface): jsPlumbToolkitTestHarness

Creates a jsPlumbToolkitTestHarness with the given Surface and returns it. This is the method you'll want to use in order to use the testing API in your own applications.

toolkit:jsPlumbToolkit

The underlying jsPlumbToolkit instance.

surface:Surface

The underlying surface widget

jsplumb:jsPlumbInstance

The underlying community instance which renders the edges

dragConnection(obj1:string|Node|Group|Port, obj2:string|Node|Group|Port, callbacks?:any):void

Connect, using the mouse, obj1 to obj2. This will throw an Error if either or both of the arguments cannot be resolved. Any interceptors you have setup on the underlying Toolkit instance will be invoked - this functions just as if the user had used the mouse to drag a connection from one object to the other.

  • obj1 An node/group/port ID, or node/group/port, or a DOM element.
  • obj2 An node/group/port ID, or node/group/port, or a DOM element.
  • callbacks Optional map of callbacks for the connection.

dragANodeAround(obj:string|Node|Group|Element):void

Randomly drag a Node or Group around. You can use this, for instance, if you just want to test that a move listener is working.

  • obj A Node/Group ID, or Node/Group, or a DOM element.

dragAnElementAround(el:Element):void

Randomly drag a DOM element around.

  • el The DOM element to drag.

load (options:LoadOptions):void

Shortcut to the underlying load method of the toolkit.

  • options Options to the Toolkit's load method.

clear():void

Shortcut to the underlying clear method of the toolkit.

getRenderedElement(obj:string|Node|Group|Port\Element):Element

For the given argument, find and return the corresponding DOM element.

  • obj A node/group/port id, or node/group/port, or a DOM element.

getRenderedConnection(obj:string|Edge):Connection

For the given argument, find and return the underlying Connection used to render it.

  • obj An edge ID, or an Edge.

dragNodeIntoGroup(node:string|Node|Element, group:string|Group|Element):void

Drag the given node into the given group.

  • node Node id, Node, or DOM element.
  • group Group id, Group, or DOM element.

getGroup (obj:string|Element|Group):Group

Gets a Group from the underlying Toolkit.

  • obj Group Id, DOM element, or Group.

getNode (obj:string|Element|Node):Node

Gets a Node from the underlying Toolkit.

  • obj Node Id, DOM element, or Node.

getToolkitObject(obj:string|Element):Node|Group|Port|Edge

Find the corresponding Toolkit object for the given input.

  • obj A string representing an ID, a DOM element, or an existing Toolkit object.

dragNodeTo(obj:string|Node|Group|Element, x:number, y:number):void

Drag the given Node/Group to the given [x,y], which are canvas coordinates.

  • obj Node id, node, or DOM element.
  • x Location on canvas in X axis to position top left corner of the node.
  • y Location on canvas in Y axis to position top left corner of the node.

dragNodeBy(obj:string|Node|Group|Element, x:number, y:number):void

Drag the given Node/Group by the given x/y amounts.

  • obj Node id, node, or DOM element.
  • x Amount to move in X axis
  • y Amount to move in Y axis

dragElementBy(el:Element, x:number, y:number):void

Drag the given DOM element by the given x/y amounts.

  • el DOM element.
  • x Amount to move in X axis
  • y Amount to move in Y axis

connect(source:string|Node|Port|Group, target:string|Node|Port|Group, data?:any):Edge

Connect the given source and target via a call on the Toolkit, ie. without using the mouse. Returns an Edge.

  • source Node/Port/Group id, node/port/group, or DOM element.
  • target Node/Port/Group id, node/port/group, or DOM element.
  • data Optional data for the edge.

dragGroupTo(obj:string|Group|Element, x:number, y:number):void

Drag the given Group to the given [x,y], which are canvas coordinates.

  • obj Group id, group, or DOM element.
  • x Location on canvas in X axis to position top left corner of the group.
  • y Location on canvas in Y axis to position top left corner of the group.

trigger(obj:string|Node|Port|Group|Element, eventName:string, evt:Event):void

Trigger the event with the given name on the given object. By default the event will occur in the middle of the DOM element representing the object.

  • obj Node/Port/Group id, node/port/group, or DOM element.
  • eventName eg 'click', 'mouseover'
  • evt Optional, an event you previously created via makeEvent. Sometimes you want to control the specific location of an event.

makeEvent(obj:string|Node|Port|Group|Element, dx?:number, dy?:number):Event

Synthesize an event for the given object. The return value of this is declared as type Event but note that this Event type is the Toolkit's internal testing event type, not an Event as you might know it from Typescript.

  • `obj Node/Port/Group id, node/port/group, or DOM element.
  • dx Optional offset from the center of the x axis of the related DOM element to position the event.
  • dy Optional offset from the center of the y axis of the related DOM element to position the event.

getEdge(edgeId:string)

Gets an Edge.

  • edgeId ID of the Edge to retrieve

updateEdge(edge:string|Edge, data:any):void

Updates an Edge.

  • edge Edge, or edge ID.
  • data Data to update the edge with.

getAllEdges():Array

Gets all edges in the underlying Toolkit.

getRenderedPort(obj:string|Port):Endpoint

Gets the Endpoint that was rendered for some Port.

  • obj Port, or port ID.

addNode(data:any):Node

Add a Node to the Toolkit.

  • data Data for the Node.

updateNode(obj:string|Node, data:any):void

Update a Node in to the Toolkit.

  • obj Node, or Node Id.
  • data Data for the Node.

clickOnNode(nodeId:string):void

Clicks on the node with the given ID.

  • nodeId ID of the node to click on.

clickOnElementInsideNode(nodeId:string, selector:string):void

Clicks on an element inside the node with the given ID.

  • nodeId ID of the node to click on.
  • selector CSS selector identifying the child element to click on.

clickOnEdge(spec:string|Edge):void

Clicks on the given edge

  • spec ID of the edge, or the Edge

clickOnOverlay(edgeSpec:string|Edge, overlayId:string):void

Clicks on the overlay with the given ID, on the given Edge.

  • edgeSpec ID of the Edge, or the Edge
  • overlayId ID of the overlay to click on.

clickOnPort(nodeId:string, portId:string):void

Clicks on the port with the given ID on the node with given node id.

  • nodeId ID of the node containing the port
  • portId ID of the port to click on.

getEdgeCount():number

Returns the count of Edges in the underlying Toolkit.

configureUndoRedo(options:DropManagerOptions):jsPlumbToolkitDropManager

Create a new Undo manager and attach to our Surface. This method is probably not something you'll need to use much - it exists for us to test the drop manager itself. In your applications if you have a drop manager then you'll want to test how it integrates - for which, see the dragElementToCanvas method below.

  • options Options for the underlying jsPlumbToolkitDropManager.

dragElementToCanvas(el:Element, x?:number, y?:number)

Drag the given element onto the canvas, optionally at a specific x,y. Use this when you want to test drag/drop from some palette.

  • el Element to drop onto the canvas.
  • x Optional, defaults to 250.
  • y Optional, defaults to 250.