Implementation:Getgauge Taiko Gauge Spec Format

Knowledge Sources	Taiko Gauge Documentation
Domains	Testing, BDD, Specification
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete format for writing human-readable test specifications in Gauge's Markdown-based syntax, as demonstrated by Taiko's functional test suite.

Description

Gauge specifications (.spec files) use a Markdown-based syntax where headings, bullet points, and tables have special meaning for the test runner. The Taiko repository contains 15 specification files under test/functional-tests/specs/ that exercise the full range of Taiko browser automation APIs.

Key syntactic conventions:

• Heading level 1 (# Title or === underline) — Specification name. One per file.
• Heading level 2 (## Title or --- underline) — Scenario name. Independent test case.
• Asterisk lines (* Step text) — Steps matched to @Step-decorated methods.
• Angle-bracket parameters (<paramName>) — Dynamic values replaced at runtime.
• Pipe-delimited tables — Data-driven test parameters.
• Tags (tags: tagName1, tagName2) — Enable selective execution via gauge run --tags.

Usage

This format is used when authoring test scenarios that describe expected browser behavior in natural language. Specifications drive step implementation development and serve as living documentation.

Code Reference

Source Location

• Repository: Taiko
• Reference Files:
  • test/functional-tests/specs/ — All specification files
  • docs/integrating_with_test_runners.md — Integration documentation

Example Specification

Elements API
============

Combo Box
---------
* Navigate to "http://localhost:3001/HTMLElements"
* Select "2" of Combo Box near "Combo Box"
* Assert text is not empty
  |Type|Selector|
  |----|--------|
  |text|2       |

Check Box
---------
* Navigate to "http://localhost:3001/HTMLElements"
* Check Box "Male"

I/O Contract

Inputs

Name	Type	Required	Default	Description
.spec file	Markdown text	Yes	—	Gauge Markdown specification with headings, steps, and optional data tables.

Outputs

Name	Type	Description
Parsed specification	Gauge internal	Specification object with scenarios, steps, and parameters that the runner matches against step implementations.

Related Pages

Implements Principle

• Principle:Getgauge_Taiko_Gauge_Specification_Authoring

Requires Environment

• Environment:Getgauge_Taiko_Node_Runtime

See Also

• Getgauge_Taiko_Gauge_Init — Project initialization that creates the specs/ directory
• Getgauge_Taiko_Gauge_Step_Decorators — Step implementations that match specification steps
• Getgauge_Taiko_Gauge_Run — Execution of authored specifications