Principle:Getgauge Taiko Gauge Specification Authoring

Field	Value
Page Type	Principle
Repository	Getgauge_Taiko
Domains	Testing, BDD
Implemented By	Implementation:Getgauge_Taiko_Gauge_Spec_Format

Overview

Practice of writing human-readable test specifications in Markdown format that define test scenarios in natural language.

Description

Gauge specifications (.spec files) describe test scenarios using Markdown syntax with special conventions recognized by the Gauge framework. The Taiko repository contains 15 specification files under test/functional-tests/specs/ that exercise the full range of Taiko browser automation APIs. These files demonstrate all core specification features: scenario definitions, parameterized steps, data tables, and tag-based filtering.

The key syntactic conventions are:

• Heading level 1 (# Title or === underline) denotes the specification name. Each .spec file contains exactly one specification.
• Heading level 2 (## Title or --- underline) denotes a scenario within the specification. Each scenario is an independent test case.
• Asterisk-prefixed lines (* Step text) denote steps that the Gauge runner matches against @Step-decorated functions in implementation files.
• Angle-bracket parameters (<paramName>) within step text are replaced with literal values or table-driven data at runtime.
• Pipe-delimited tables provide inline data for data-driven steps or parameterized scenarios.
• Tags (written as tags: tagName1, tagName2 on the line after a heading) enable selective test execution via gauge run --tags.

For example, the ElementsAPI.spec file uses the === / --- underline style for headings and includes scenarios like "Combo Box", "Check Box", "Radio Button", "Text Box", and "Page", each exercising specific Taiko APIs through natural language steps.

The browserActions.spec file demonstrates data table parameters with pipe syntax:

* Assert Exists

   |Type|Selector            |
   |----|--------------------|
   |text|Opening a new window|

And the tag feature is used in ElementsAPI.spec to mark known issues:

Radio Button without for
------------------------
tags: knownIssue
* Radio Button "Y"

Usage

• Write specifications before implementing step definitions. They serve as the requirements document that drives automation development.
• Use them to capture acceptance criteria and test scenarios during planning or grooming sessions.
• Collaborate with product owners and business analysts to validate test coverage -- the natural language format requires no programming knowledge to read.
• Review specification files in pull requests to ensure new features have corresponding test scenarios.
• Use tags to organize tests into categories such as smoke, regression, or knownIssue for selective execution in CI/CD pipelines.

Theoretical Basis

Gauge specification authoring follows the Behavior-Driven Development (BDD) pattern:

• Specifications define expected behavior in natural language, serving as the single source of truth for what the system should do.
• Step implementations provide the technical execution, mapping each natural language step to browser automation code.
• The specification acts as living documentation -- it is always in sync with the actual test automation because the tests fail if the specification and implementation diverge.

This approach differs from traditional unit testing in that:

• The test description language (Markdown) is separate from the implementation language (TypeScript/JavaScript).
• Test scenarios are readable by non-technical stakeholders.
• The same step text can be reused across multiple scenarios and specifications, promoting a shared vocabulary (ubiquitous language in Domain-Driven Design terms).

The data table feature supports the Specification by Example pattern, where concrete examples of inputs and expected outputs replace abstract requirements. This reduces ambiguity and makes edge cases explicit.

Related Pages

Implemented By

• Implementation:Getgauge_Taiko_Gauge_Spec_Format

Related Principles

• Principle:Getgauge_Taiko_Gauge_Project_Setup -- Project structure that contains the specs/ directory
• Principle:Getgauge_Taiko_Gauge_Step_Implementation -- The code that implements the steps declared in specifications
• Principle:Getgauge_Taiko_Gauge_Test_Execution -- Running the authored specifications