jsharmony-test v1.4.3
==============
jsharmony-test
==============
Testing tools for jsHarmony
Installation
- 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
Setup
- 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
Running Tests
- 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
Overview
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 }
Command: Navigate
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"
Command: Screenshot
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": ""
}
]
}
Command: Wait
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
Command: Input
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"
Command: Click
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"
Command: Set
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
Command: JS
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
Command: Assert
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
Selectors and Getters
ELEMENT_SELECTOR
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
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_GETTER
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.
Examples
Configuration for testing a login page
{
"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" },
],
}
Tools
jsharmony test recorder
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
Release History
- 1.0.0 Initial release