5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<div class="intro">
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith When creating automated tests for your application or modules, you need
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith to be able to mock user events. The DOM supports creating native events
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith that behave essentially the same as user generated events, though
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith without the associated browser default behaviors (e.g. following a link
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The `event-simulate` module adds the `Y.Event.simulate` method for
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith working with raw DOM nodes, but for most cases, the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `node-event-simulate` module is the right choice, since it allows you
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith to call the `simulate` method directly from the `Node`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h2>Simulating Mouse Events</h2>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith There are seven mouse events that can be simulated:
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`click`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`dblclick`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`mousedown`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`mouseup`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`mouseover`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`mouseout`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`mousemove`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Each event is fired by calling <code>simulate()</code> and passing in two
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith arguments: the type of event to fire and an optional object specifying
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith additional information for the event. To simulate a click on the document's
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith body element, for example, the following code can be used:
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithYUI().use('node-event-simulate', function(Y) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Y.one("body").simulate("click");
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith This code simulates a click with all of the default properties on the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <code>event</code> object. To specify additional information, such as the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Shift key being down, the second argument must be used and the exact DOM
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith name for the event property specified (there is browser-normalizing logic
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith that translates these into browser-specific properties when necessary):
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithY.one("body").simulate("click", { shiftKey: true });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith In this updated example, a click event is fired on the document's body
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith while simulating that the Shift key is down.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The extra properties to specify vary depending on the event being simulated
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith and are limited to this list:
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <dt>`detail`</dt>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Indicates the number of times a button was clicked (DOM-compliant
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith browsers only).
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <dt>`screenX`, `screenY`</dt>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Coordinates of the mouse event in relation to the entire screen
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith (DOM-compliant browsers only).
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <dt>`clientX`, `clientY`</dt>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Coordinates of the mouse event in relation to the browser client
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <dt>`ctrlKey`, `altKey`, `shiftKey`, `metaKey`</dt>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The state of the Ctrl, Alt, Shift, and Meta keys, respectively
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith (true for down, false for up).
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <dt>`button`</dt>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The button being used for the event, 0 for left (default), 1 for
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith right, 2 for center.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <dt>`relatedTarget`</dt>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the element the mouse moved from (during a `mouseover` event) or to
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith (during a `mouseout` event).
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithYUI().use('node-event-simulate', function(Y) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith var node = Y.one("#myDiv");
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a click Alt key down
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("click", { altKey: true});
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a double click with Ctrl key down
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("dblclick", { ctrlKey: true });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a mouse over
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("mouseover", { relatedTarget: document.body });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a mouse out
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("mouseout", { relatedTarget: document.body });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a mouse down at point (100,100) in the client area
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("mousedown", { clientX: 100, clientY: 100 });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a mouse up at point (100,100) in the client area
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("mouseup", { clientX: 100, clientY: 100 });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a mouse move at point (200, 200) in the client area
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("mousemove", { clientX: 200, clientY: 200 });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h2>Simulating Key Events</h2>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<p>There are three key event simulations available:</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`keyup`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`keydown`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`keypress`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith As with the mouse events, key events are simulated using
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <code>simulate()</code>. For <code>keyup</code> and <code>keydown</code>,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the <code>keyCode</code> property must be specified; for
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <code>keypress</code>, the <code>charCode</code> property must be included.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith In many cases, <code>keyCode</code> and <code>charCode</code> may be the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith same value to represent the same key (97, for instance, represents the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith "A" key as well as being the ASCII code for the letter
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith "a"). For example:
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithYUI().use('node-event-simulate', function(Y) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith var node = Y.one("#myDiv");
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a keydown on the A key
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("keydown", { keyCode: 97 });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a keyup on the A key
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("keyup", { keyCode: 97 });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate typing "a"
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.simulate("keypress", { charCode: 97 });
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Key events also support the <code>ctrlKey</code>, <code>altKey</code>,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <code>shiftKey</code>, and <code>metaKey</code> event properties.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <strong>Note:</strong> Due to differences in browser implementations, key
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith events may not be simulated in the same manner across all browsers. For
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith instance, when simulating a keypress event on a textbox, only Firefox will
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith update the textbox with the new character of the key that was simulated to
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith be pressed. For other browsers, the events are still registered and all
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith event handlers are called, however, the textbox display and
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <code>value</code> property are not updated. These differences should go
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith away as browser support for simulated events improves in the future.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h2>Simulating UI Events</h2>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<p>There are several UI event simulations available:</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`blur`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`change`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`focus`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`resize`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`scroll`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li>`select`</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith As with the other events, UI events are simulated using
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <code>simulate()</code>. There are no properties that are required to
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith simulate UI events as these events don't carry extra information. Some
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithYUI().use('node-event-simulate', function(Y) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith var node = Y.one("#myInput");
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a change event
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith //simulate a select event
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h2>Caveats and Coming Soons</h2>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h3 id="faking">Don't use simulation in user facing code</h3>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Event simulation is for automated testing. Your application should respond
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith to real user events. For reasons
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="#only-what-you-ask-for">mentioned below</a>, it can be easy to get
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith your application into a confused runtime state when some callbacks have
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith been executed but not others.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Typically, event simulation is sought to trigger certain callbacks. If a
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith function needs to respond to user action or be called programmatically, it
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith should be written accordingly and called directly in the latter case.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Often a better solution is to extract the core logic from the event handler
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith into a separate function and call that method from the event handler and
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith from the other part of the application that was going to use simulation.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith In some cases, simulation is wanted because there may be any number of
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith subscriptions on a node, and all applicable callbacks should be triggered.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith If this is the case, investigate using <a
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith href="../event-custom/index.html">custom events</a>, instead.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The bottom line is, reliance on event simulation in production code is a
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith warning sign that the architecture is not scaling. The affected code
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith should be refactored before it becomes a larger problem.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h3>Only what you ask for</h3>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith In many cases, events happen in groups (`mousedown`, `mouseup`, `click`, or
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `keydown`, `keyup`, `keypress`). If you simulate an event that is
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith typically part of a group or is often followed by other events, <em>the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith other events will NOT be generated</em> for free.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith For example, if you simulate a `click` event on a submit button, you only
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith simulate the `click` event. The preceding `mousedown` and `mouseup`, as
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith well as the subsequently expected 'submit' are neither simulated or fired
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h3>No touch events yet</h3>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Currently, there's no support for simulating touch events or other events
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith not noted explicitly above.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h3>No synthetic event simulation yet</h3>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The <a href="synths.html">Synthetic event system</a> doesn't yet support
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith defining simulation. In most cases, though, synthetic events are triggered
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith by other DOM events that can be simulated, so it's often possible to
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith trigger them by simulating the underlying events. But that ignores the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith point that synthetic events are supposed to mask that abstraction for your
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Support for synthetic event simulation is on the roadmap.