Principle:Getgauge Taiko Gauge Project Setup

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

Overview

Process of initializing a Gauge test framework project structure for browser automation testing with Taiko.

Description

Gauge is a lightweight test automation framework that separates test specifications (written in Markdown) from step implementations (written in code). Setting up a Gauge project involves installing the Gauge CLI, initializing a project scaffold with a manifest, environment configuration, specifications, and step implementation directories. The Gauge+Taiko combination provides readable acceptance tests where business stakeholders can understand test scenarios written in natural language while testers implement the automation in JavaScript or TypeScript.

The Taiko repository's own functional test suite (located at test/functional-tests/) serves as the canonical reference implementation of a Gauge+Taiko project. It demonstrates all required configuration files, directory conventions, and dependency declarations needed for a working project.

A properly initialized Gauge+Taiko project contains these core artifacts:

• manifest.json -- Declares the project language and active plugins. In the Taiko repository this is test/functional-tests/manifest.json, which specifies "Language": "ts" and "Plugins": ["html-report", "screenshot"].
• env/default/ -- Contains environment property files that control runtime behavior such as headless mode, report directories, and test timeouts.
• specs/ -- Contains .spec files written in Gauge Markdown format that define test scenarios in natural language.
• tests/ -- Contains TypeScript or JavaScript files with step implementation classes decorated with @Step, lifecycle hooks (@BeforeScenario, @AfterScenario, etc.), and Taiko browser automation calls.
• package.json -- Declares npm dependencies including taiko, gauge-ts (or gauge-js), and @getgauge/cli.
• tsconfig.json -- When using TypeScript, configures experimentalDecorators and emitDecoratorMetadata to enable gauge-ts decorator support, and includes taiko in the types array for type definitions.

Usage

Use this principle when:

• Starting a new browser automation test suite that requires readable test specifications.
• Enabling collaboration between testers and business analysts through natural language test scenarios.
• Integrating browser automation tests with CI/CD pipelines that need structured reporting.
• Setting up a project where non-technical team members need to review and validate test coverage.
• Migrating existing Taiko scripts from standalone execution to a managed test framework with reporting and parallel execution support.

Theoretical Basis

The Gauge project scaffold follows a convention-over-configuration pattern. Rather than requiring extensive configuration files, the framework uses a fixed directory structure with well-known paths:

• manifest.json at the project root declares the language runner and active plugins.
• env/ holds environment-specific property files, with env/default/ as the baseline configuration.
• specs/ holds .spec files that define test scenarios.
• tests/ holds step implementation files that map natural language steps to executable code.

This separation of concerns follows the Specification by Example methodology, where:

• Specifications define what should happen in business-readable language.
• Step implementations define how the automation executes each step.
• Environment configuration defines where and under what conditions tests run.

The project structure also aligns with the Dependency Inversion Principle -- specifications depend on abstract step definitions, not on concrete browser automation APIs. This allows changing the underlying automation tool without modifying the test specifications.

Related Pages

Implemented By

• Implementation:Getgauge_Taiko_Gauge_Init

Related Principles

• Principle:Getgauge_Taiko_Gauge_Specification_Authoring -- Authoring the spec files within the project structure
• Principle:Getgauge_Taiko_Gauge_Step_Implementation -- Implementing the step definitions within the tests/ directory
• Principle:Getgauge_Taiko_Gauge_Environment_Configuration -- Configuring the env/ property files
• Principle:Getgauge_Taiko_Gauge_Test_Execution -- Running the initialized project