domtest

DomTest

Describe DOM Tests with ease: less code, less words.

• MaskJS syntax
• jQuery 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 contexts 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

<div class='foo baz' onclick="this.style.display = 'none'">Foo</div>
<input value='A' />

Test suite sample:

// finds all `.foo` elements and sets them for assertion scope
find ('.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()

  DomTest(Element: Node, MaskTestSuite | Array<MaskTestSuite>): Runner

  Create 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 and selenium can be evaluated in Node.JS only, and domlib 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 components
• function: Custom function

Runners

Domlib

Uses jQuery-like dom library to test HtmlElements in browser. (@default)

DomTest(document.body, `
    find ('button') {
        click;
        text ('Foo');
    }
`);

jMask

Uses jMask library to test MaskAST in browser or Node.js

var template = 'section > input placeholder="Foo";'
DomTest
    .use('jmask')
    .process(template, `
        find('input') {
            attr placeholder Foo;
        }
    `);

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
    .use('cheerio')
    .process(template, `
        find('input') {
            attr placeholder Foo;
        }
    `);
 
DomTest
    .use('cheerio')
    .process('http://google.com', `
        find('input') {
 
        }
    `);

Selenium

Uses selenium-webdriver module to test the Web Pages

DomTest
    .use('selenium', Options)
    .process('https://developer.mozilla.org/en/', `
        find('input[name=q]') {
            type XmlHttpRequest;
            trigger submit;
        }
        await ('.result-list') {
            prop tag ul;
            children {
                notEq length 0;
                eq (1) {
                    has text XmlHttpRequest;
                }
            }
        }
    `);

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