Testing tools for jsHarmony
- Ensure that the jsharmony-cli is installed with
npm install -g jsharmony-cli
- Install jsharmony-test in the project folder
npm install jsharmony-test --save
- Create a folder in the project root named "test"
- Create a subfolder for the test scripts, ex. "test/module1"
- Create a _config.json file in the "test/module1" folder with the test configuration:
{
"server": "https://server:port", // Application URL, ex: https://localhost:8000
"appbasepath": "<path-to-test>", //(Optional) Path to application base, defaults to current working directory
"datadir": "---", //(Optional) Path to application data folder, defaults to appbasepath/data
"screenshot": { ... } //(Optional) Screenshot configuration, if screenshots are taken. Full screenshot configuration options are listed under the screenshot command below.
"namespace": "", //(Optional) Root namespace
"require": [] //(Optional) Run the tests in this array before any other tests in this test set, used in scenarios such as login / authentication
"before": [ COMMAND1, COMMAND2, ... ] //(Optional) Array of commands to run before running any other tests in this test set (command syntax defined below)
"after": [ COMMAND1, COMMAND2, ... ] //(Optional) Array of commands to run after running the tests in this test set (command syntax defined below)
}
- Create a .json file for each test script within the test folder, ex "test/module1/test1.json"
{
"id": "TEST_ID",
"title": "Test Name",
"batch": "01_Test", //(Optional) Batch ID used to sort test sequence
"require": [ "TEST_ID1", "TEST_ID2" ], //(Optional) Array of tests that must be executed before this test. Used to sort tests
"commands": [ COMMAND1, COMMAND2, ... ], //Array of commands to run within this test script (command syntax defined below)
}
- The "test" folder should now appear as follows
└───test
└───module1
_config.json
test1.json
- Create the test master screenshots
jsharmony test master screenshots test\handheld
- Optionally use the --show-browser argument to preview in the browser
- Run the tests, to compare the current application against the master screenshots
jsharmony test screenshots test\handheld
- Optionally use the --show-browser argument to preview in the browser
Commands are defined as JSON. Each command requires an "exec" parameter to define the command name, and can optionally have a "timeout" parameter to specify a maximum timeout for that command. The COMMAND_NAME may be any of the commands described below.
{ "exec": "COMMAND_NAME", "timeout": 10000 }
The "navigate" command is used to redirect the test browser to a new URL.
{ "exec": "navigate", "url": "https://localhost:3000" }
- The url property can use variables, e.g., "https://localhost:3000/App?token=@TOKEN"
The "screenshot" command is used to take a screenshot of the current browser window.
{ "exec": "screenshot", "id": "login_start" }
//The following optional screenshot parameters are available:
{
"x": 0, //Take screenshot starting at X position
"y": 0, //Take screenshot starting at Y position
"width": 950, //Set browser width before taking screenshot
"height": 700, //Set browser height before taking screenshot
"beforeScreenshot": "", // Execute server-side JS code before taking screenshot
"onload": "", // Execute client-side JS code before taking screenshot
"cropToSelector": ".container", // Crop screenshot to DOM selector
"postClip": { // Clip screenshot to target size
"x": 1,
"y": 1,
"width": 1,
"height": 1
},
"trim": true, // Trim blank pixels from edge of screenshot
"exclude": [ // Draw a black box over target areas, to prevent false positive errors in screenshot comparison
{ //Exclude region based on absolute rectangle
"x": 1,
"y": 1,
"width": 1,
"height": 1
},
{ //Exclude region based on DOM selector
"selector": ""
}
]
}
The "wait" command pauses test execution until a specified condition is met.
{ "exec": "wait" }
//Example usage:
{ "exec": "wait", "element": ".homePage" }
{ "exec": "wait", "text": "Welcome!" }
- Optional Parameters:
- "element": ELEMENT_SELECTOR // Selector for the target element
- "text": TEXT_COMPARE // The element or any child element containing the text (defined below)
- If no element is specified, wait for any child of the document containing the text
- "while_waiting": [ COMMAND1, COMMAND2 ] // Execute commands while the wait operation is in progress
The "input" command performs key presses or enters data into elements.
{ "exec": "input", "element": "ELEMENT_SELECTOR", "value": "John Doe" }
- The syntax for ELEMENT_SELECTOR is defined below.
- Value can also contain:
- \r (For "enter key")
- {SPECIAL_KEY} (For special keys as defined in the Puppeteer KeyInput object), e.g., {Backspace}
- {SPECIAL_KEY1}{SPECIAL_KEY2} (Multiple simultaneous special key presses)
- List of special keys can be found in the Puppeteer KeyInput documentation
- If the input is a checkbox, the value can be:
- true :: checked
- false :: unchecked
- "true" :: checked
- "false" :: unchecked
- When using variables, the value can be:
- "@VARIABLE"
- or contain additional characters, such as "EXAMPLE@VARIABLE\n"
The "click" command uses the mouse to interact with the user interface.
{ "exec": "click", "element": "ELEMENT_SELECTOR" }
- The syntax for ELEMENT_SELECTOR is defined below.
- Optional Parameters:
- "button": "left", "right", "middle"
The "set" command saves data from the user interface or page into memory.
{ "exec": "set", "variable": "VARIABLE", "value": "VALUE_GETTER" }
- The syntax for VALUE_GETTER is defined below.
- Variables are stored in the jsHarmonyTestConfig.variables object
The "js" command can be used to execute arbitray JavaScript. Promises should be used to wait for the operation to complete before moving to the next command.
{ "exec": "js", "js": "return new Promise(function(resolve,reject){ resolve(); });" }
- Parameters passed to the JS function:
- jsh - jsHarmony instance
- page - Puppeteer Page
- callback - Callback. If a Promise is returned by the JS, wait for the Promise to resolve
The "assert" command checks whether a page element displays an expected value.
{ "exec": "assert", "element": "ELEMENT_SELECTOR", "value": "TEXT_COMPARE" }
- The syntax for ELEMENT_SELECTOR and TEXT_COMPARE is defined below.
- Optional Parameters:
- "error": "Container missing target text" // Error description
Element selectors are used to specify an element in the user interface.
{ "selector": "SELECTOR" } //CSS Selector for an element
{ "selector": "SELECTOR", "visible": true } //Require element to be visible
//Example usage:
{ "exec": "wait", "element": {"selector": ".targetElement", "visible": true} },
As a shorthand,
{ "element": "SELECTOR" }
is equivalent to
{ "element": { "selector": "SELECTOR" } }
Text compare expressions are used to check whether a source string matches an expected value.
{ "equals": "text" } //Text string must be exact match
{ "not_equals": "text" } //Text string must not match
{ "contains": "text" } //Text string contains target text
{ "not_contains": "text" } //Text string contains target text
{ "begins_with": "text" } //Text string begins with target text
{ "ends_with": "text" } //Text string ends with target text
{ "regex": "text.*" } //Regex match
{ "equals": "text", "case": "sensitive" } //Default is case sensitive
{ "equals": "text", "case": "insensitive" } //Case insensitive comparison
//Example usage:
{ "exec": "wait", "text": { "contains": "Target Text" } }
As a shorthand,
{ "text": "TEXT" }
is equivalent to
{ "text": { "contains": "TEXT" } }
Value getters are used to extract the value of an element property from the user interface.
{ "element": “selector”, "property": "text" }
//Example usage:
{ "exec": "set", "variable": "Variable name", "value": { "element": ".targetElement", "property": "text" } }
- Optional Parameters:
- "regex": "ID (.*)" Parse resulting text, and extract first match
- Property can be:
- "text", or any element property, ex. "innerHTML", "clientHeight", etc.
{
"id": "login",
"title": "Login",
"commands": [
{ "exec": "navigate", "url": "/" },
//Put app token into a variable
{ "exec": "set", "variable": "APPTOKEN", "value": { "element": ".loginLink", "property": "href", "regex": "app\\_token=(.*)" } },
{ "exec": "navigate", "url": "/login?app_token=@APPTOKEN" },
// Waits for text to render before continuing
{ "exec": "wait", "text": { "contains": "Please enter username" } },
{ "exec": "screenshot", "id": "Login" },
{ "exec": "input", "element": ".username", "value": "testUser" },
{ "exec": "screenshot", "id": "Username" },
{ "exec": "click", "element": ".loginButton" },
],
}
The test recorder tool launches a browser and records the user interactions to generate a test script.
jsharmony test recorder
- Optional flags:
- --full-element-paths: return full element paths instead of shortest unique path
- 1.0.0 Initial release