Syn is used to simulate user actions. It creates synthetic events and performs their default behaviors.

Basic Use

The following clicks an input element with id='description' and then types 'Hello World'.

     Syn.click({},'description')
     .type("Hello World")

User Actions and Events

Syn is typically used to simulate user actions as opposed to triggering events. Typing characters is an example of a user action. The keypress that represents an 'a' character being typed is an example of an event.

While triggering events is supported, it's much more useful to simulate actual user behavior. The following actions are supported by Syn:

• click - a mousedown, focus, mouseup, and click.
• dblclick - two click! events followed by a dblclick.
• [Syn.prototype.key key] - types a single character (keydown, keypress, keyup).
• [Syn.prototype.type type] - types multiple characters into an element.
• [Syn.prototype.move move] - moves the mouse from one position to another (triggering mouseover / mouseouts).
• [Syn.prototype.drag drag] - a mousedown, followed by mousemoves, and a mouseup.

All actions run asynchronously. Click on the links above for more information on how to use the specific action.

Asynchronous Callbacks

Actions don't complete immediately. This is almost entirely because focus() doesn't run immediately in IE. If you provide a callback function to Syn, it will be called after the action is completed.
The following checks that "Hello World" was entered correctly:

     Syn.click({},'description')
     .type("Hello World", function(){

     ok("Hello World" == document.getElementById('description').value)  
     })

Asynchronous Chaining

You might have noticed the then method. It provides chaining so you can do a sequence of events with a single (final) callback.

If an element isn't provided to then, it uses the previous Syn's element.

The following does a lot of stuff before checking the result:

     Syn.type('ice water','title')
     .type('ice and water','description')
     .click({},'create')
     .drag({to: 'favorites'},'newRecipe',
     function(){
     ok($('#newRecipe').parents('#favorites').length);
     })

 <h2>jQuery Helper</h2>
 If jQuery is present, Syn adds a triggerSyn helper you can use like:

     $("#description").triggerSyn("type","Hello World");

Key Event Recording

Every browser has very different rules for dispatching key events. As there is no way to feature detect how a browser handles key events, synthetic uses a description of how the browser behaves generated by a recording application.

If you want to support a browser not currently supported, you can record that browser's key event description and add it to Syn.key.browsers by it's navigator agent.

     Syn.key.browsers["Envjs\ Resig/20070309 PilotFish/1.2.0.10\1.6"] = {
     'prevent':
     {"keyup":[],"keydown":["char","keypress"],"keypress":["char"]},
     'character':
     { ... }
     }

Limitations

Syn fully supports IE 6+, FF 3+, Chrome, Safari, Opera 10+. With FF 1+, drag / move events are only partially supported. They will not trigger mouseover / mouseout events.
Safari crashes when a mousedown is triggered on a select. Syn will not create this event.

Contributing to Syn

Have we missed something? We happily accept patches. The following are important objects and properties of Syn:

• Syn.create - contains methods to setup, convert options, and create an event of a specific type.
• Syn.defaults - default behavior by event type (except for keys).
• Syn.key.defaults - default behavior by key.
• Syn.keycodes - supported keys you can type.

Roll Your Own Functional Test Framework

Syn is really the foundation of JavaScriptMVC's functional testing framework - FuncUnit. But, we've purposely made Syn work without any dependencies in the hopes that other frameworks or testing solutions can use it as well.

Constructor

Creates a synthetic event on the element.

new Syn(type, options, element, callback) -> undefined