Principle:Getgauge Taiko Gauge Step Implementation

Field	Value
Page Type	Principle
Repository	Getgauge_Taiko
Domains	Testing, Test_Framework
Implemented By	Implementation:Getgauge_Taiko_Gauge_Step_Decorators

Overview

Practice of mapping natural language test steps to browser automation code using framework decorators and lifecycle hooks.

Description

Step implementation is the bridge between human-readable Gauge specifications and executable Taiko browser automation. Using the gauge-ts package, developers create TypeScript classes where methods are annotated with decorators that the Gauge runner discovers and invokes at runtime.

The Taiko repository's functional test suite (under test/functional-tests/tests/) contains 10 step implementation files that collectively map over 80 step definitions to Taiko API calls. The architecture consists of:

Step Decorators:

• @Step("step text with <parameters>") -- Maps a natural language step pattern to an async method. Parameters in angle brackets become method arguments. For example, from tests/htmlElementAPI.ts:

@Step("Navigate to <url>")
public async navigate(url: string) {
    await goto(url);
}

• @ContinueOnFailure() -- Combined with @Step, allows a scenario to continue executing subsequent steps even if this step fails. Used in the Taiko tests for scroll operations that may not always succeed:

@ContinueOnFailure()
@Step("Scroll the page right by pixels <pixels>")
public async scrollPageByPixel(pixels: string) {
    await scrollRight(parseInt(pixels, 10));
}

Lifecycle Hooks:

• @BeforeScenario() -- Executes before each scenario. In the Taiko test suite, this opens a browser instance with configured arguments (headless mode, sandbox flags, window size).
• @AfterScenario() -- Executes after each scenario. Closes the browser to ensure clean state.
• @BeforeSuite() -- Executes once before all scenarios. Starts the test server and configures Taiko settings via setConfig().
• @AfterSuite() -- Executes once after all scenarios. Stops the test server.
• @CustomScreenshotWriter() -- Provides a custom screenshot capture function for Gauge's failure reporting system.

Class-Based Organization:

Step implementations are organized into classes by functional area. The Taiko test suite uses:

• hooks.ts -- Lifecycle management (browser open/close, server start/stop, screenshot capture)
• htmlElementAPI.ts -- HTML element interactions (forms, dropdowns, checkboxes, scrolling)
• browserAction.ts -- Browser-level actions (tabs, cookies, navigation, geolocation)
• click.ts -- Click operations
• write.ts -- Text input operations
• selectors.ts -- Element selection strategies
• assert.ts -- Assertion steps
• pageActions.ts -- Page-level operations
• dropDown.ts -- Dropdown-specific interactions
• alert.ts -- Dialog/alert handling

Usage

• Implement step definitions after writing Gauge specifications -- let the specification drive what steps need to be coded.
• Keep step implementation methods focused on a single action -- delegate complex logic to helper functions.
• Use lifecycle hooks to manage shared resources (browser instances, test servers) rather than repeating setup/teardown in each step.
• Leverage @ContinueOnFailure() judiciously for non-critical assertions where you want to collect multiple failures in a single scenario run.
• Organize step implementations into classes by functional domain to maintain readability as the test suite grows.

Theoretical Basis

The step implementation pattern follows the Adapter Pattern from object-oriented design:

• The Target Interface is the natural language step text defined in specifications.
• The Adaptee is the Taiko browser automation API (goto, click, write, etc.).
• The Adapter is the decorated method that translates between the two.

The lifecycle hook system implements the Template Method Pattern:

• The Gauge runner defines the skeleton of the test execution algorithm (setup, execute steps, teardown, report).
• Concrete hook implementations fill in the specific setup and teardown behavior (open browser, start server, capture screenshots).

The decorator-based approach relies on TypeScript's experimental decorator feature, requiring experimentalDecorators: true and emitDecoratorMetadata: true in tsconfig.json. At compile time, decorators attach metadata that the Gauge runner reads at test discovery time to build the step-to-method mapping.

Related Pages

Implemented By

• Implementation:Getgauge_Taiko_Gauge_Step_Decorators

Related Principles

• Principle:Getgauge_Taiko_Gauge_Specification_Authoring -- The specifications that declare the steps implemented here
• Principle:Getgauge_Taiko_Gauge_Project_Setup -- Project structure that hosts the tests/ directory
• Principle:Getgauge_Taiko_Gauge_Environment_Configuration -- Configuration consumed by lifecycle hooks