Principle:Getgauge Taiko Gauge Test Execution

Field	Value
Page Type	Principle
Repository	Getgauge_Taiko
Domains	Testing, CI_CD, DevOps
Implemented By	Implementation:Getgauge_Taiko_Gauge_Run

Overview

Process of running Gauge test suites with reporting, parallel execution, and containerized deployment support.

Description

Test execution is the culmination of project setup, specification authoring, step implementation, and environment configuration. The Gauge runner orchestrates the full lifecycle: discovering step implementations, matching them to specification steps, executing scenarios in order, capturing failures with screenshots, and generating HTML reports.

The Taiko repository's functional test suite defines its execution command in test/functional-tests/package.json:

{
  "scripts": {
    "test": "gauge run -v --tags=\\!knownIssue --simple-console"
  }
}

This command demonstrates several execution features:

• gauge run -- Invokes the test runner against the default specs directory.
• -v -- Verbose output for detailed execution logging.
• --tags=\!knownIssue -- Tag-based filtering that excludes scenarios tagged with knownIssue. The ! prefix negates the tag match.
• --simple-console -- Simplified console output format suitable for CI environments.

Execution Lifecycle:

The Gauge runner follows this sequence for each run:

1. Suite Initialization -- Executes @BeforeSuite() hooks. In the Taiko test suite, this starts the test HTTP server and calls setConfig({ navigationTimeout: 60000 }).
2. Specification Discovery -- Scans the specs/ directory for .spec files, filtered by tags if specified.
3. For each specification:
   1. For each scenario:
      1. Execute @BeforeScenario() hooks -- Opens a fresh browser instance with configured arguments.
      2. Execute each step by matching step text against @Step()-decorated methods.
      3. On step failure: invoke @CustomScreenshotWriter() to capture the browser state.
      4. Execute @AfterScenario() hooks -- Closes the browser instance.
4. Suite Teardown -- Executes @AfterSuite() hooks. Stops the test server.
5. Report Generation -- Generates HTML reports in the directory specified by gauge_reports_dir.

Parallel Execution:

Gauge supports parallel execution at the specification level with gauge run --parallel or gauge run -p -n=4 (4 parallel streams). Each parallel stream gets its own browser instance, enabling significant speed improvements for large test suites.

Containerized Execution:

For CI/CD pipelines, the Gauge+Taiko test suite can run inside Docker containers. This requires specific browser launch arguments to handle the containerized environment:

await openBrowser({
    headless: headless,
    args: [
        "--disable-gpu",
        "--disable-dev-shm-usage",
        "--disable-setuid-sandbox",
        "--no-first-run",
        "--no-sandbox",
        "--no-zygote",
        "--window-size=1440,900",
    ],
});

These flags (sourced directly from test/functional-tests/tests/hooks.ts) address common Docker/CI issues: --no-sandbox for unprivileged containers, --disable-dev-shm-usage for limited shared memory, --no-zygote to avoid process forking issues, and --disable-gpu for environments without GPU access.

Usage

• Local development -- Run npm test or gauge run specs/ to execute the full suite. Use gauge run specs/specificFile.spec to run individual specifications during development.
• CI/CD pipelines -- Run with --simple-console for clean log output, headless mode for no-display environments, and tag filtering to separate smoke tests from full regression.
• Docker execution -- Build a Docker image with Node.js, Gauge, and Taiko installed. Set TAIKO_BROWSER_ARGS for container-specific flags. Mount a volume for report extraction.
• Debugging failures -- Enable screenshot_on_failure = true in properties, check the HTML report for failure screenshots, and use DEBUG = true in js.properties for runner-level debugging.

Theoretical Basis

The test execution model follows the Test Runner Pattern common in xUnit-style frameworks, adapted for the BDD specification format:

• Test Discovery -- The runner scans for specifications and resolves step-to-method bindings at startup, similar to reflection-based test discovery in JUnit or pytest.
• Fixture Management -- Lifecycle hooks (@BeforeSuite, @BeforeScenario, etc.) implement the Setup/Teardown Pattern, ensuring each test runs in a clean, predictable state.
• Failure Isolation -- Each scenario gets a fresh browser instance (opened in @BeforeScenario, closed in @AfterScenario), implementing the Fresh Fixture pattern that prevents state leakage between tests.
• Reporting -- The HTML report plugin implements the Observer Pattern, listening to test execution events and generating a structured report artifact.

Parallel execution follows the Shared Nothing Architecture -- each parallel stream operates independently with its own browser instance and specification subset, avoiding synchronization overhead.

The containerized execution approach aligns with Infrastructure as Code principles -- the Docker image captures the complete test environment (OS, Node.js, browser, Gauge, Taiko), making test results reproducible across any host that can run Docker.

Related Pages

Implemented By

• Implementation:Getgauge_Taiko_Gauge_Run

Related Principles

• Principle:Getgauge_Taiko_Gauge_Project_Setup -- The project structure that the runner operates on
• Principle:Getgauge_Taiko_Gauge_Specification_Authoring -- The specifications that the runner discovers and executes
• Principle:Getgauge_Taiko_Gauge_Step_Implementation -- The step implementations that the runner invokes
• Principle:Getgauge_Taiko_Gauge_Environment_Configuration -- The configuration that controls execution behavior