bitovi / syn

Standalone Synthetic Event Library

Syn

For questions or discussion, check out our forums.

If you are looking for the Synergy project, you can find it here. Thanks postquagga for letting us use the name!

Syn lets you simulate user behavior like typing, clicking, moving, and dragging exactly how a real user would perform those actions.

Syn.click( 'hello' )
   .type( 'Hello World' )
   .drag( 'trash' );

Install

Install Syn via the command line with npm:

> npm install syn

or bower:

> bower install syn

Or by downloading it here.

Inside the download, npm package and bower package, there are the following folders:

• dist/global/syn.js - A standalone file that can be used with a <script> tag.
• dist/amd - An AMD build that can be used with RequireJS and other AMD loaders.
• dist/cjs - A CommonJS build that is used by node or browserify.
• src - The source files that can be loaded by StealJS, SystemJS, and eventually JSPM.

Setup

The following walk you through how to load Syn into various environments.

Node / Browserify

Assuming you installed with npm, simply require("syn") like the following:

var syn = require("syn");
syn.click(document.getElementById('hello'));

StealJS

If you installed via NPM or Bower and are using the npm or bower module for configuration, you can use import, require, or define to load the syn module without any configuration.

import syn from "syn";
syn.click(document.getElementById('hello'));

AMD / RequireJS

Add the following package configuration:

require.config({
    packages: [{
        name: 'syn',
        location: 'PATH/TO/syn/dist/amd',
        main: 'syn'
    }]
});

PATH/TO should be the path from your baseUrl to the location of the syn folder. Once this is properly configured, you should be able to write:

define(['syn'], function(syn){
  syn.click(document.getElementById('hello'));
});

Script Tag / Standalone

If you don't use a module loader, you can simply add the following to your page:

<script src='PATH/TO/dist/syn.js'></script>

PATH/TO should be the path to the installed syn folder.

Use

syn.click( element [, options][, callback] )

syn.dblclick( element [, options][, callback] )

syn.type( element, text [, callback] )

syn.key( element, key [, callback] )

syn.delay( time=600 )

syn.drag( element, optionsOrTarget [, callback])

Contributing

Check out the contribution guide.

Relevant Links

1. Blog post introducing Syn — a Standalone Synthetic Event Library
2. Gitter chat

syn's Issues

triggerSyn only works with _ prefixed types

// This adds something to the queue but it doesn't seem to ever get called.
$(...).triggerSyn('type', 'text', function() { console.log('example'); });

// This does work.
$(...).triggerSyn('_type', 'text', function() { console.log('example'); });

There's a comment inside .then() where it says
//if stack is empty run right away
//otherwise ... unshift it

Only the first case of running right away is a lie, it won't run right away if the stack is empty. In general it looks like all the examples that use "type" as the event type are wrong, and that it should always be an _ prefixed version (_type, _click, _drag, ...) like in the docs for .then() ?

Link to documentation is broken

I'm looking at this page, and it looks like the following two links are broken:

• http://v3.javascriptmvc.com/index.html#&who=Syn
• http://v3.javascriptmvc.com/index.html#&who=Syn.static.keycodes

Wanted to check the keycodes docs.. but.. can't find em

Exception in firefox 4.0 :(

I'm getting an exception in firefox 4

var el = document.createElement('input');
Syn.click(el).key('j');

uncaught exception: [Exception... "Component returned failure code: 0x80004005 (NS_ERROR_FAILURE) [nsIDOMHTMLInputElement.selectionStart]" nsresult: "0x80004005 (NS_ERROR_FAILURE)" location: "JS frame :: file:///Users/jacob/workspace/evnt/support/syn/key.js :: <TOP_LEVEL> :: line 8" data: no]

Clicking button[type=button] shouldn't submit form when clicked

From bitovi/funcunit#82

Some problems with events: click, mouseup, mousedown, and change for Chrome

Chrome 40.0.2214.111 m

click event

`event.originalEvent.fromElement should = null vs <html>
event.screenX and event.screenY don't seem to match the values clientX/Y, pageX/Y, etc

mousedown and mouseup events

event.originalEvent.__proto__ should = KeyBoardEvent vs Event
event.view should = vs undefined

the following are missing entirely:
event.originalEvent.detail: 0
event.originalEvent.keyIdentifier: "U+xx58"
event.originalEvent.keyLocation: 0
event.originalEvent.layerX: 0
event.originalEvent.layerY: 0
event.originalEvent.location: 0
event.originalEvent.pageX: 0
event.originalEvent.pageY: 0
event.originalEvent.repeat: false
event.originalEvent.view: Window

change event

I couldn't get the change event to fire at all. It doesn't fire if you type in an input field then click somewhere else:

syn.type($("#b"), "x")
syn.click($("#a"))

Even if one of those events is done manually, the change event doesn't happen. I also noticed that if an input is in focus, and a click happens on say, a div, the input doesn't lose focus as it would in a manual click.

License file

Hello, I'm using syn inside another open source framework released under the Apache license.
Could you please include a license information to the project so that I can include a correct license header to the files that are a derivative of your work?

Regards

Improve standalone build

The standalone build has some kind of AMD shim exposed globally.

This make it impossible to use in an environment WITHOUT AMD but with libraries which DOES support AMD.

Currently I had to add this line after syn.js

<script>delete window.define;</script>

I think a Browserify build is a better solution, as it does not pollute the global namespace.

Hope this help

Use StealJS for DoneJS-style application structure

• Write Syn in ES6
• Export to AMD / CJS / Standalone
• Make it available in browserify

Update package.json to use preversion, version, and postversion

Update package.json to use preversion, version, and postversion
Example: https://github.com/canjs/can-set/blob/master/package.json

//...
  "scripts": {
    "preversion": "npm test && npm run build",
    "version": "git commit -am \"Update dist for release\" && git checkout -b release && git add -f dist/",
    "postversion": "git push --tags && git checkout master && git branch -D release && git push",
    "release:patch": "npm version patch && npm publish",
    "release:minor": "npm version minor && npm publish",
    "release:major": "npm version major && npm publish",
    "jshint": "jshint src/. --config",
    "testee": "testee test.html --browsers firefox",
    "test": "npm run jshint && npm run testee",
    "build": "node build.js"
  },
//...

Modifier keys aren't working for typed sequences.

So I ran into something where the modifier keys (Shift, Alt, etc.) weren't being toggled for a key sequence because the 'Syn.support.ready' value wasn't the value of 2 as is necessary to run the setup functions for those events.

This value is incremented by code in key.support.js and mouse.support.js (once in each, hence the value of 2), but these files are not included in the 'syn.js' and 'syn.min.js' files produced by the Grunt build.

I went ahead and set this value in other JS code that lives in the same space as Syn and all is well, but it's pretty hacky. Others might be having trouble with this as it's subtle and not-at-all easy to diagnose. I wasn't sure what the best way to fix this was, so I thought I'd just report it as an issue.

'key' module tests failing in Firefox 4

Hi,

Syn.type() is adding one extra character when running in Firefox 4.

    Sync.type("bb", $('textarea')); // ends up typing "bbb"

I ran the Syn unit tests in FF4 and several tests are failing.

-Bri

npm install results in git seeing local changes

The package.json file used to have:

//...
  "scripts": {
    "test": "./node_modules/.bin/grunt test --stack",
    "prepublish": "./node_modules/.bin/grunt build"
  },
//...
  "scripts": {
    "test": "grunt test"
  },
//...

With #100, I changed it to the following to remove duplicate scripts:

//...
  "scripts": {
    "test": "grunt test",
    "prepublish": "./node_modules/.bin/grunt build"
  },
//...

npm install now does a build, and git sees modified local files. Should it do this, or should the prepublish option be removed from scripts?

Drag to support text selection

The typing sequence "[shift][[shift-up]" isn't handled properly

It seems that the keys syn tries to type from "[shift][[shift-up]" are "shift" then "[shift-up". Since "[shift-up" isn't anything, you get an invalid event. Does syn have a way of escaping the "[" key? Syn should be able to figure out that since "[[shift-up]" isn't a correct sequence, that the first character of it should be handled by itself.

In chrome.

NPM release?

It'd be nice to have this on npm, for those of us that use that as our package manager.

Using [shift] in conjunction with lowercase letters produces incorrect events.

If I run syn.type for the sequence "[shift]a[shift-up]", the charCode in the keypress ends up being lower case 'a' and the shiftKey property of the event is false.

Offer: Can I write documentation?

Can I write some documentation in the readme? Would you accept a pull request? Are these all the functions: click, dblClick, move, drag, key, type, rightClick?

Anyways, I keep needing to refer back to the code to figure things out for this, and it'd be nice if could write some docs here that I could then refer to instead.

Is it possible to interact with a radio button via synthetic keyboard?

I'm trying to use key or type to type tabs and arrow key directions on radio buttons to test their focus and selection behavior, but I'm getting the error:

InvalidStateError: Failed to read the 'selectionStart' property from 'HTMLInputElement': The input element's type ('radio') does not support selection.
    at undefined
    at Error (undefined)
    at getSelection (http://localhost:8100/src/external/syn.js:1553:19)
    at h.extend._key (http://localhost:8100/src/external/syn.js:2123:116)
    at new extend.init (http://localhost:8100/src/external/syn.js:104:27)
    at syn (http://localhost:8100/src/external/syn.js:80:20)

Which seems to be coming from

getSelection(element)

Make it easy to test

I couldn't find an easy way to write an automatic test for a form using selectize. There's the setTextboxValue but I'm not sure it works completely and it doesn't handle multiple values.

I found a solution (see this SO question) but it would be nice to have a method to set all values at once (or did I miss it?)

Dragged element doesn't move in IE9 and older

I am making drag/move specs with Syn. Everything works great with modern browsers but this does not work in IE9 and older: http://jsfiddle.net/7K3PR/
Tried same thing with jQuery and same result: http://jsfiddle.net/L35CN/

I can see the Syn red dot moving, having the correct starting point and trajectory, but the element does not move.

Any pointers on what can change to get this working?

Thank you!

Test: configurable support

Configured support needs a set of tests in a separate environment(from qunit.html)

Is it possible to combine clicks with keyboard events?

I'm trying to test a multi-select component, where if you shift-click on options, you can select multiple options. I've tried this:

syn.type(select1.children[0].domNode, "[shift]")
syn.click(select1.children[0].domNode)
syn.type(select1.children[0].domNode, "[shift-up]", function() {
    console.log("donezo")
})

But it doesn't seem to work. The click happens, but the shift doesn't seem to be incorporated. is it currently possible to do what i'm trying to do?

npm install fails

I just updated to the latest version in git and did an npm install on windows 8, and got this message:

D:\billysFile\code\javascript\nodejs\modules\syn>npm install
npm ERR! Failed resolving git HEAD (git://github.com/bitovi/steal) fatal: ambiguous argument 'ie8-fixes': unknown revision or path not in the working
tree.
npm ERR! Failed resolving git HEAD (git://github.com/bitovi/steal) Use '--' to separate paths from revisions, like this:
npm ERR! Failed resolving git HEAD (git://github.com/bitovi/steal) 'git <command> [<revision>...] -- [<file>...]'
npm ERR! Failed resolving git HEAD (git://github.com/bitovi/steal)
npm ERR! Error: Command failed: fatal: ambiguous argument 'ie8-fixes': unknown revision or path not in the working tree.
npm ERR! Use '--' to separate paths from revisions, like this:
npm ERR! 'git <command> [<revision>...] -- [<file>...]'
npm ERR!
npm ERR!     at ChildProcess.exithandler (child_process.js:647:15)
npm ERR!     at ChildProcess.emit (events.js:98:17)
npm ERR!     at maybeClose (child_process.js:755:16)
npm ERR!     at Process.ChildProcess._handle.onexit (child_process.js:822:5)
npm ERR! If you need help, you may report this *entire* log,
npm ERR! including the npm and node versions, at:
npm ERR!     <http://github.com/npm/npm/issues>

npm ERR! System Windows_NT 6.2.9200
npm ERR! command "C:\\Program Files\\nodejs\\\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install"
npm ERR! cwd D:\billysFile\code\javascript\nodejs\modules\syn
npm ERR! node -v v0.10.29
npm ERR! npm -v 1.4.14
npm ERR! code 128
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR!     D:\billysFile\code\javascript\nodejs\modules\syn\npm-debug.log
npm ERR! not ok code 0

support for touch* events

Are you planning to support tablet touch* events such as touchstart and touchend? It would be nice if Syn.click() can trigger touchstart and touchend events when ran on a tablet device.

Any way to achieve this in the meanwhile?

Thanks

IE8 bugs

What are the supported browsers by Syn?

My application has to support IE8 and above so I'd like to run my specs against it, but IE8 doesn't implement Array.prototype.indexOf which is used a lot in Syn code.

I could certainly patch IE8 on my specs where syn are used, but then I wouldn't know for sure if the tests passes independent from the patch in the test environment.

Drag events

Apparently Syn.drag raises only the events mousedown, mousemove and mouseup. Would it be possible to trigger also dragstart, dragover and drop?

Syn.click does not fire focus event

The event focus is not fired when using Syn.click. This should be the default behaviour because a user click will also trigger a focus.

Although the blog says: "A click is the following sequence of events followed by the event’s default actions:

• mousedown
• focus (Called only if the element was focusable, and mousedown’s default actions were not prevented)
• mouseup
• click"

this is not true. Notice the JavaScriptMVC documentation states: "Clicks an element by triggering a mousedown, mouseup, and a click event." (http://v3.javascriptmvc.com/docs.html#&who=Syn.prototype.click). This is indeed how it is implemented now, but a focus should be fired too.

Removed 3.3.1 tag?

Hello. My project depends on the Syn package@~3.3.1 through bower. This tag does not exist anymore, even in bitovi/legacy-syn. I found that no other tags are there, either.

Can these tags be restored?

How do I run tests?

I checked out the repo and opened test/clickbasic.html in the browser. It didn’t work:

GET file://localhost/Users/nv/steal/steal.js  clickbasic.html:16
Uncaught ReferenceError: steal is not defined 

I cloned Steal to /Users/nv/steal. Now it misses stealconfig.js. Where do I get it?

Why have both `key` and `type`?

Looks like syn.type basically just loops over a string and calls key multiple times. Why not just expose type, since it seems to have a superset of the functionality key has?

Suggestion: use a futures API rather than callbacks

So instead of writing:

    syn.type(a, "x", function() {
        syn.click(b, function() {
            syn.click(c, function() {
               syn.click(d)
           })
        })
    })

you could write something like:

syn.type(a, "x").then(function() {
     return syn.click(b)
}).then(function() {
     return syn.click(c)
}).then(function() {
     return syn.click(d)
}).done()

so you don't get all stuck in callback hell. I'd suggest a futures library but i don't wanna plug my stuff too much all at once ; )

Use CustomEvent where supported

document.createEvent is deprecated:

https://developer.mozilla.org/en-US/docs/Web/API/document.createEvent

Multiple keys like Shift+1

Hi @matthewp!

I wonder how can I make Syn trigger shift+1 to get !?
Using Syn.type('[shift]1[shift-up]', 'textInput') I get a 1 instead of !.
I would like to simulate that for the specs of a javascript framework. Is this possible with Syn?

I made this jsFiddle to test this, check the console.
(A jsFiddle demo could also be a nice to use it as a demo/example in your Docs)

Special keys are not working ([insert], [ctrl], [alt], [caps])

Syn.click({}, el).type("[caps]aaa"); // types "capsaaa". Expected: "AAA"

Syn.click({}, el).type("[ctrl]"); // types "ctrl". Expected: ""

Syn.click({}, el).type("[ctrl]")
// ...
Syn.click({}, el).type("a"); // behave like ctrl is pressed.

How to unpress [ctrl] after type("[ctrl]")?

ReferenceError: checkSupport is not defined

I added the standalone version to my page and get this error.

I don't find any declaration of this function in the code.

Did I missed something ?

Incorrect unbind for inputs and textarea's blur handler

I noticed that after my test, typing manually into textareas and input fields yeilded two change events instead of one. Looking at the code, it looks like this is because line 270 is incorrectly written as unbind(element, "blur", focus);. It should be unbind(element, "blur", blur); and the function then obviously needs to be given the name blur.

Submitting a form should fire click on first submit button

Also, elements default to type "submit" if unspecified.

Illustrated in this jsfiddle: http://jsfiddle.net/dkordik/y25r4qnp/

I have a pull request to fix this incoming

Next release should be 0.1.0

Has api-breaking changes, specifically Syn is now syn

Setting pageX to 0 on syn.drag causes error in firefox

Example:

syn.drag($drag,{
    from: {
        pageX: 0,
        pageY: 0
    },
    to: {
        pageX: 50,
        pageY: 0
    }
}, function(){
    start();
});

Firefox error:

TypeError: Argument 1 of Document.elementFromPoint is not a finite floating-point value.

...it is caused because syn/src/drag.js tries to convert pageX to clientX in convertOption using the following check (syn/src/drag.js:168):

if (option.pageX) {
//convert to clientX
}

It can be fixed by changing syn/src/drag.js:168 to:

if (option.pageX != null) {

What's really happening is that the method elementFromPoint (syn/src/drag.js:39) uses document.elementFromPoint(clientX, clientY). In Firefox, these values must be defined.

The following code breaks in Firefox

var pageX, pageY, e = document.elementFromPoint(pageX, pageY);

Keyboard simulation doesn't fire "input" events

https://developer.mozilla.org/en-US/docs/Web/Events/input

In newer browsers, when you update an input or textarea with a value, if the length of the value changes as you are typing it will trigger an input event. We ought to update our library to fire that event.

non-steal, standalone?

According to the README, it should be possible to add syn using script tags. This no longer seems possible with 8726299.

Move documentation to markdown files

Move the documentation out to markdown files.

Fill out the API documentation

Including browsers, so we can talk about where the API is weak.

Tests are broken

The readme says all you need to do is run test/index.html but I get the following errors:

index.html:4 GET file:///omitted/syn/lib/qunit/qunit/qunit.css net::ERR_FILE_NOT_FOUND
index.html:12 GET file:///D:/omitted/syn/lib/qunit/qunit/qunit.js net::ERR_FILE_NOT_FOUND
index.html:14 Uncaught ReferenceError: QUnit is not defined
index.html:19 GET file:///D:/omitted/syn/lib/steal/steal.js net::ERR_FILE_NOT_FOUND
index.html:21 Uncaught ReferenceError: System is not defined

npm test doesn't work OOTB

Simply cloning syn, running npm install and then npm test does not work

oninput event not triggered

The oninput event should be triggered between onkeypress and onkeyup for Syn.type().

See http://help.dottoro.com/ljhxklln.php

linkHrefJS feature test appears to be causing problems in IE9 and IE10 (+ Karma?)

Situation:

For our testing we've used a pretty old version of syn (or, back then, Syn) until now. When trying to update this, we run into problems with IE9 and IE10.

I've dumbed the test environment down to just loading Karma and syn. What happens in IE9 and IE10 is that right after starting, Karma errors with "Some of your tests did a full page reload!" and stops. In IE7, IE8, IE11 and Edge everything works as expected.

After some attempts to track down the problem, I found out that this problem stops occuring when the feature test for linkHrefJS is removed. I'm not entirely sure what's going on here, but it appears that triggering a click on <a href="javascript:__synthTest()"> causes the page to reload in IE9 and IE10. The __synthTest function doesn't even get executed.

I wasn't able to determine whether this problem is related to Karma being loaded or if it's an actual compatibility problem with IE9 and IE10, but since this feature test was fixed in December 2013 (#17) I kind of assume this isn't a generic issue in these browsers.

How to reproduce:

I'd say any environment with at least Karma and syn. But I'll describe my dumbed down test environment below, assuming node and npm installed:

mkdir syn-test
cd syn-test
npm install karma syn
cat << EOF > karma.conf
module.exports = function(config){
    config.set({
        files: ['node_modules/syn/dist/syn.js']
    });
};
EOF
`npm bin`/karma start karma.conf

That starts a karma server at http://localhost:9876/.
Opening that in any browser should error "You need to include some adapter that implements __karma__.start method!" (since we didn't actually add anything to start).
In IE9 and IE10 this errors "Some of your tests did a full page reload!".

Syn doesn't handle typing various shifted characters properly

If I run syn.type for "{" or for any capitol letter (A-Z), the event comes back with a keyCode of 0 and undefined which and charCodes.

Testing in chrome.

Clean up the release process

The release process is very manual now. We should automate it so that a build is done, committed and tagged.

Syn.type not behaving as (I) expected

I just started working with Syn (which I really like). I'm using it to do some functional testing. My use case is to modify some text in a content editable div. That text happens to be inside a span. What I would have loved to have done is said to Syn "Put the insertion point at this offset of this particular textnode, then type the following characters", or "select this text at this particular offset [x,y] in this particular textnode, and type (ie replace it with) this text"...

This JS fiddle shows the problem:
http://jsfiddle.net/pK7wY/

Unfortunately I don't think Syn seems to have an awareness of where the caret is at any particular time. I've just spent some time building caret awareness into my own functional testing "suite" (if you want to call it that) because I need to test cursor position (the thing I'm building is a sort of WYSIWYG "textarea" using a contenteditable div that has enforcement rules on where the user can click or cursor to... my ideal is that it consumes clickdown and/or keydown events and doesn't let the user go beyond the set of areas, but it's also acceptable to catch them after the case and then simply move the caret back within bounds).

For example, using my code I can "click" or "select" inside a textarea or div at a particular offset and using the rangy library I actually modify the real caret position.

Would you be interested in incorporating this kind of caret awareness into Syn?

The other thing is, according to the fiddle I linked to, Syn doesn't appear to be able to type inside specific nodes within a contenteditable unless they too have contenteditable mode on. It also just seems to append chars typed to the end without any awareness of the contents of the div/textarea.