DomTest
Describe DOM Tests with ease: less code, less words.
MaskJS
syntaxjQuery
API- Works in browser and Node.js
- Supports different drivers (runners):
- jQuery or similar
- Cheerio (jQuery-alike
html
library) - Selenium-Query (jQuery-alike
webdriver
library)
- Fully async
Test Suites
All statements are of the 4 types: traversers, events, actions and assertions.
Traversers
A traverser component creates elements scope (context
) for nested components. The context
is the jQuery-alike instance.
⭐️ Components also perform assertions after query to ensure the elements are found
-
find (selector)
❗️ If no elements are found, the
filter
method is then called. -
filter (selector)
-
children (selector)
-
parent (selector)
-
closest (selector)
find ('.foo') { // do assertions in this elements scope // e.g: check that that 2 elements are in the context eq length 2;}
🎉 When selector has no whitespace ''
are optional
find (section) { // ...}
Events
An event component triggers native or custom events on current scope
trigger eventName (...args);
⭐️ Known event names don't need trigger
keyword.
blur
,focus
,resize
,scroll
,click
,dblclick
,mousedown
,mouseup
,mousemove
,mouseover
,mouseout
,mouseenter
,mouseleave
,change
,submit
,keydown
,keypress
,keyup
.
🎉 When statement has no arguments ()
are optional.
find (button) { click;}
❗️
Cheerio
driver supports no events, as it tests only html AST in Node.js environment
Actions
An action component performs some action, calls javascript functions, mutates the dom, or runs a group of actions.
Keyboard
-
type (text)
Text can contain meta key definitions in
{}
, e.g.:find ('input.foo') {type ('Hello friends!{enter}');} -
press (keyCombination)
Key combination (hotkey):
ctrl+f
,alt+c+b
,a+d
e.g.find ('input.foo') {press ('alt+f');}
Functions
A function component simply call the jQuery function.
call functionName (...args)
Select
select
component selects a text range or an option, depends on a current context
find ('input.foo') { // selects everything select; // selects range select (0, 5); // finds text and selects it select ('foo');}find ('select.city') { // select an option by `value`, or `name` or `textContent` select ('London');}
Assertions
An assertion component reads current context
s property or calls a function to compare the value with expected value.
👓 Assertion components with aliases:
equal
~eq
,notEqual
~notEq
,lessThan
~lt
,lessThanOrEqaul
~lte
,greaterThan
~gt
,greaterThanOrEqual
~gte
,deepEqual
~deepEq
,notDeepEqual
~notDeepEq
,has
,hasNot
eq propertyName (expectedValue)
eq functionName (...args, expectedValue)
🎉 As the accent in this library is made for assertions, so when no event, action, traverser, etc is found, then we assume it is the eqaul
component, so you can skip the equal
keyword.
find ('button') { // should find one element eq length (1); // same eq length 1; // same length 1;}find ('.baz') { eq attr (name, 'Baz'); // same eq attr name Baz; // same attr name Baz; // check class name eq hasClass ('baz', true); // same hasClass ('baz', true); // same hasClass baz;}
Sample
Assume this DOM
Foo
Test suite sample:
// finds all `.foo` elements and sets them for assertion scopefind ('.foo') { // check text property text Foo; hasClass baz; // perform action click; // check visibility css display none; // or is hidden; // check bg color css ('background-color', 'red');}find ('input') { val A; press backspace; type Baz; val Baz;}
Install
$ bower install domtest# or $ npm install domtest
API
-
DomTest()
: RunnerCreate default
DomLibRunner
and immediately start the test. -
DomTest.use(driver:string, settings:object): Runner
Create the Test Runner. Available runners:
'domlib'
'jmask'
'cheerio'
'selenium'
❗️ Note, that
cheerio
andselenium
can be evaluated in Node.JS only, anddomlib
in browser only,jmask
can be used in browser and Node.js
Runner
Runner implements IEventEmitter, IPromise
-
Runner::process(root:any, suite: MaskTestSuite | Array<MaskTestSuite>)
root
is the root object, which runner uses for test. Refer to the particular Runner to find out the required root-type.suite(s)
is/are the tests to be run for the root object
Events
- `.on(event, handler)`
| Event | Data | Description |
|--------|-----------| ------------|
| `fail` | `error: AssertionError` | Failed assertion |
| `success`| - | Successful assertion |
| `progress` | `runner:Runner, node: MaskNode, error:AssertionError` | On each step. `error` is null, when assertion is ok |
| `complete` | `errors:Array<AssertionError>` | Runner has finished all tests |
- `.off(event, handler)`
MaskTestSuite:string|MaskAST|function
string|MaskAST
: Mask template with the components. See the Test Suite for supported componentsfunction
: Custom function
Runners
Domlib
Uses jQuery-like dom library to test HtmlElements in browser. (@default
)
;
jMask
Uses jMask library to test MaskAST in browser or Node.js
var template = 'section > input placeholder="Foo";'DomTest ;
Cheerio
Uses cheerio module to test HTML in Node.js.
❗️ No actions are available here, as no listeners can be attached to plain HTML.
var template = '<section><input placeholder="Foo"></section>';DomTest ; DomTest ;
Selenium
Uses selenium-webdriver
module to test the Web Pages
DomTest ;
Options default
name: 'Chrome' args: 'no-sandbox' binaryPath: null
For more information, please refer to sources: config.es6
❗️ you can override functions to set any webdriver option you need.
©️ MIT The AtmaJS Project