Story And Steps Hooking

As in most E2E test framework, story (or test suite) is the basic runnable unit to test one or several related features. The test engine of handow can consume stories meeting the following specification.

• A story is a .feature text file with simplified Gerhkin language.
• There are 2 types scenarios in Handow - Given scenario and When scenario. The only difference between them is the Given scenario starts with a Given step and the When scenario starts with a When step.
• A story is composed with one or more scenarios, and the 1st scenario must be Given scenario. Scenario Syntax
• We can add optional tags to a story.

For example, the login.feature file is a valid story including 4 scenarios and it is tagged with "form" and "admin" keywords.

    @tags: ["form", "admin"]

    @scenario: Open the Login form
    # The body of the 1st 'Given' scenario

    @scenario: Username and password validation
    # The body of a 'When' scenario

    @scenario: Submit valid username and password
    # The body of a 'When' scenario

    @scenario: Naviagte to secured resource after login success
    # The body of a 'When' scenario

We will use the form_1.feature as an example to invegate story syntax, which is a demo story in handow-seed project.

Scenario syntax

A scenario is the smallest test operation in Handow engine.

• A scenario has a label annotated with @scenario:.
• A scenario could be skipped (except the Given scenario) by evaluating condition expression in run-time, which is annotated with @skip: ().
• A scenario must include Action steps (Given/When ...) and Verification steps (Then ...).
• In a scenario, all Action steps should be ahead of all Verification steps.
• Parameters could be attached in the end of a scenario, which is annotated with @parameters: [{...}, ...].

A valid scenarion example, it is a scenario in the handow-seed demo story - form_1.feature_*.

@scenario: Submit the form and verify message in different modes
@skip: (this.Skip_Form)
When I click {selector: "Submit_Button"}
And I wait {selector: "Spin"} disappeared
Then I can see {selector: "Feedback_Message"} showing {text: "Success_No_Secured"} @skip: (this.Secured)
And I can see {selector: "Feedback_Message"} showing {text: "Success_Secured"} @skip: (!this.Secured)
@parameters: [
    {
        Spin: "#ajax-loading-spin",
        Feedback_Message: "#form-feedback",
        Success_No_Secured: "Submit successfully",
        Success_Secured: "Submit secured form successfully"
    }
]

Steps hooking

The statement lines in a scenario are test-steps, e.g., When I click {selector: "Submit_Button"}. The literal statement is a label hooking a step function. When a scenario is evaluated by story runner, all the steps are called in sequential with the passed parameters. Along with each step executing, the test result is written to current record.

The step function of the literal step When I click {selector}

async (selector, browser, page, config) => {
    await page.waitForSelector(selector, {
        state: 'visible',
        timeout: config.elementAppearTimeout
    });
    const elements = await page.$$(selector);
    await page.evaluate(el => el.click(), elements[0]);
}

It seems like writing steps should be the main task of the E2E test project, but it is not actually. The most outstanding feature of Handow is the steps reusing solution.

• Some general steps are defined in Handow built-in library, developers can reuse them for most test requirements.
• Maybe developers need to create a couple of special steps dedicated for current application. They can follow the format of the built-in steps to add custom steps. Then the custom steps will be merged into the built-in steps repository.
• Developers needn't worry about the step functions running cycle and report generating. Handow engine will take care about all of them.

Anyway, None Coding Test is the goal of Handow.

Questions

Please read the tech topic if you have these questions.

• The scenarios running order
• What is the valid expression for @skip: () condition?
• Can I customize the labels of the built-in steps?
• Why the steps are trivial and verbose?

Related documents

Steps Library

Parameters

Design Test Plan