JSRobot is a testing utility for webapps that can generate real keystrokes rather than just simulating the JavaScript events firing. This allows the keystroke to trigger the built-in browser behavior in addition to firing any JavaScript listeners which wouldn't otherwise be possible.
JSRobot was originally created to increase the amount of functionality in Ephox Enterprise TinyMCE that can be covered by automated tests. It forms a part of our on-going efforts to improve the quality and functionality of TinyMCE. We've released it as open source in the hope that it will be useful to others.
Usage
The two required files are robot.js and JSRobot.jar, they must be on the same server as the HTML page and should be in the same directory as each other.
Include the robot.js file at the end of the body tag. It will create then provide a window.robot object which JavaScript tests can interact with. Note that the robot loads asynchronously - you can use the onload method to be notified when it is ready for use.
Since JSRobot utilises a signed Java applet, you should run the tests once manually on your build server and permanently accept the security certificate. After that, it will run in an automated build without producing any dialogs.
Example
Set up the robot and type the 'A' in a text field.
<input type="text" id="content" />
<script src="robot.js"></script>
<script>
function runTest() {
var content = document.getElementById('content');
content.focus();
window.robot.type('a', true, function() {
assertEquals('A', content.value);
});
}
window.robot.onload(runTest);
</script>Note that both the initialization of JSRobot and the type function are asynchronous, so we use callbacks to ensure the action has completed before continuing.
The tests for JSRobot itself are a good source of further examples on how to use it.
Download
API Documentation
All APIs are provided on the window.robot object which is automatically created when the robot.js script is included.
Setup
onload(function)
Calls the function parameter when the robot is ready to use or immediately if the robot is already set up.
Typing
type(key, shiftKey, callback)
Types the specified key, optionally with the shift key down. Since JavaScript must run to completion, the keystroke must happen asynchronously. The callback function is called after the keystroke has occurred.
Specifying Keys
JSRobot doesn't type characters, it actually simulates pressing specific keys on the keyboard using a Java applet and the java.awt.Robot class. As such, when specifying the key to type, you are specifying a virtual key based on the Java KeyEvent system.
JSRobot can automatically convert the characters a-z (or A-Z) for the standard alphabetic keys, plus \t for tab, \n for enter and \b for backspace to the appropriate key code. For other keys, it can accept the Java numeric code for the key directly.
typeAsShortcut(key, callback)
Type the specified key with the platform modifier key pressed. The key can be specified in the same was as for the type function.
cut(callback)
Type the keyboard shortcut for cut. This is a good way to test cut behavior without triggering browser security restrictions.
copy(callback)
Type the keyboard shortcut for copy. This is a good way to test the copy behavior without triggering browser security restrictions.
paste(callback)
Type the keyboard shortcut for paste. This is a good way to test the copy behavior without triggering browser security restrictions.
forwardDelete(callback)
A utility function to simplifying typing the forward delete key. As with type, the key is typed asynchronously and the callback function is then called.
Screenshots
captureScreenShot()
Take a screen shot (of the whole screen) and save it to the local client machine. Returns the full path to the screenshot file on disk.
setScreenShotDirectory(string)
Set the local directory on the client that screenshots are saved to. Each screen shot is automatically given a unique name.
License
JSRobot is released under the Apache License Version 2.0.
