Handow Outline

Handow is a Node.js test engine basing on Playwright APIs. Users can implement handow module to create robust E2E web test application quickly. In most situation users just need clone handow-seed to obtain a full featured UAT project including the test engine and handow-SHM server.

How handow works

The atomic running units in handow are steps. A step is a function to perform definite "action" or "verification" operation on current page by invoking Playwright APIs. The results of steps running are recorded together with the page snapshots like shcreenshot, XHR, cookies and cosole errors, and they are materials to generate testing reports.

Handow provides a built-in steps library which covered most often used testing operations, and also provide mechanism to merge additional steps created by user. All custom steps are compiled with built-in steps together into 2 step-bundles, which are step factories active in run time. So any step, either built-in or custom, must be consitent with the Handow Step Specification.

A single step cannot finish a comprehensive testing cycle. Like other E2E test frameworks, handow also use Story and Scenario to dispatch steps. The steps are shared by different stories, instantiated with parameters in scenarios, running over and over to complete the testing flow. Story And Steps Hooking

Handow provides the plan solution to control testing coverage, testing conditions and the testing flow. Staged stories in a plan can apply multiple workers running stories in parallel. When handow is called to run, the target is always a plan. (Handow can run a single story by wrapping it with an internal plan).

The test report is gerenated per plan, it is a compound JSON file and a set of .jpg screenshots. Handow has an embedded report renderer to present the report with HTML documents.

Steps builder

Actually the prototype steps are not a valid JS function, it is a template friendly for developers. For example:

Then("I verify the input {selector} with value {text}", async (selector, text) => {
    await page.waitForSelector(selector, { state: "visible", timeout: config.elementAppearTimeout });
    const _value = await page.$eval(selector, (el) => el.value);
    expect(_value.trim()).toBe(text.trim());
});

The step-builder will process all steps and build them to bundle files - /stepBundles/actsBundle.js and /stepBundles/factsBundle.js. It's mandatory to rebuild steps for updating the step bundles after changed. Handow APIs And Commands

Story parser

Users 'mention' the test flow with simplified Gherkin language and tags to create story (.feature) files. The statements in a story hook relevant steps and pass parameters to step function in run time. Story And Steps Hooking.

Handow story parser will parse the literial content of a story file to an object, the story-objects are consumed by story runner. Once a story is going to run. handow will parse it automatically, users can also call the parser specifically with the API or CLI. Handow APIs And Commands

Runners

There are 3 runners defined in handow.

• Step Runner - Call step function and apply parameters, write to record buffer when the step finished.
• Story Runner - Iterate the story object, instantiate testing context with parameter, control the testing flow and put steps to run one by one.
• Plan Runner - Interpret the plan file, instantiate testing environment (e.g., creating browser context, loading data from file system and setup configuration), parse literal stories into objects, create new test record and archive the existed reports, and call workers to run stories in sequential or in parallel.

The Step Runner and Story Runner are not available to Handow API and CLI, only the Plan Runner could be invoked from outside. Handow APIs And Commands

Test output, records and report renderer

Handow has abilities to output real time testing info to console, write testing result to record files and render record files with HTML documents. The console output is only available when run handow with CLI. The static HTML renderer is deprecated, users can install handow-shm to render reports with its management UI.

Handow APIs And Commands

Handow Report Demo