Principle:Getgauge Taiko Script Execution

Knowledge Sources	Taiko
Domains	Browser_Automation, Testing
Last Updated	2026-02-12 00:00 GMT

Overview

Mechanism for executing pre-written browser automation scripts with configurable runtime behavior such as observe mode and wait times.

Description

Script execution takes a JavaScript file containing browser automation commands and runs it in an environment where all automation API functions are available in the global scope. This eliminates the need for explicit import statements in the script file, allowing scripts to be concise and focused entirely on the automation logic rather than boilerplate setup.

The execution environment can be configured for different purposes:

• Observe mode -- When enabled, each automation step pauses briefly and highlights the target element on the page before interacting with it. This provides a visual trace of the automation execution, making it easy to follow what the script is doing. Observe mode is invaluable during development and debugging because it transforms an instantaneous sequence of commands into a visible, step-by-step walkthrough.
• Headless mode -- Runs the browser without a visible UI window. This is the standard mode for CI/CD pipelines and server environments where no display is available, and where execution speed is prioritized over visual feedback.
• Custom wait times -- The observe delay and navigation timeouts can be configured to match the characteristics of the application under test. Slow applications or those running on loaded servers may require longer wait times to avoid false timeout failures.

An optional continuation mode (the --load flag) allows entering the REPL after script execution completes. This is particularly useful for debugging test failures: the script runs until completion (or failure), and then the tester can interactively inspect the browser state, try alternative selectors, or execute additional commands to understand what went wrong.

Usage

Use script execution in the following scenarios:

• Running generated test scripts -- Execute scripts that were previously generated from REPL sessions using the .code command. This is the natural next step after exploratory testing and code generation.
• Running hand-written test scripts -- Execute manually authored automation scripts from the command line using taiko script.js.
• CI/CD pipeline integration -- Run scripts in headless mode as part of automated build and deployment pipelines. The exit code indicates success or failure for pipeline integration.
• Visual debugging with observe mode -- Enable observe mode (--observe flag) during development to watch each automation step execute with visual highlighting. This helps identify timing issues, incorrect selectors, or unexpected page states.
• Interactive debugging with continuation mode -- Use the --load flag to enter the REPL after the script finishes. This allows interactive exploration of the browser state at the point where the script ended, which is especially useful for diagnosing test failures.
• Configuring execution speed -- Adjust the observe delay (--wait-time) to control how long the script pauses between steps in observe mode. Longer delays make it easier to follow visually; shorter delays speed up observed execution.

Theoretical Basis

The script execution model leverages Node.js's module system to create a controlled execution environment that simplifies script authoring while maintaining full configurability. The execution follows a well-defined sequence:

Pseudocode: Script Execution Pipeline

function runFile(filePath, options):
    1. INJECT API functions into global scope
       FOR EACH function in taiko API:
           global[functionName] = taikoFunction
       This allows scripts to call click(), goto(), write(), etc.
       without any require() or import statements.

    2. CONFIGURE execution mode
       IF options.observe THEN
           SET observe mode = true
           SET observe delay = options.waitTime OR default (3000ms)
       IF options.headless THEN
           SET headless mode = true

    3. LOAD and EXECUTE the script
       RESOLVE absolute path of filePath
       CALL require(absolutePath)
       -> Node.js loads, compiles, and executes the script
       -> Script commands execute against the configured browser

    4. HANDLE execution result
       IF script throws error THEN
           REPORT error with stack trace
           SET exit code = 1
       ELSE
           SET exit code = 0

    5. OPTIONALLY enter REPL for continuation
       IF options.load THEN
           INITIALIZE REPL with current browser state
           HAND OFF control to interactive REPL loop
       ELSE
           EXIT with appropriate exit code

This execution model embodies several important design principles:

Global scope injection is the key technique that separates script authoring from execution environment setup. Script authors write simple, readable function calls:

await openBrowser();
await goto("https://example.com");
await click("Sign In");
await write("user@example.com", into(textBox("Email")));
await press("Enter");
await closeBrowser();

The execution environment handles the complex configuration (which browser binary to use, what CDP port to connect on, whether to run headless, what timeouts to apply) entirely behind the scenes. This follows the Separation of Concerns principle: scripts describe what to do, while the execution environment determines how to do it.

Observe mode implements the Observer pattern at the automation level. When enabled, a hook is inserted before each automation action that:

1. Highlights the target element on the page (by injecting a CSS overlay).
2. Pauses for the configured delay duration.
3. Removes the highlight.
4. Proceeds with the actual action.

This non-intrusive instrumentation does not change the behavior of the automation commands themselves -- it only adds visibility. The same script produces the same results whether observe mode is on or off, ensuring that development-time debugging does not affect production-time behavior.

Continuation mode implements a form of breakpoint debugging without requiring a traditional debugger. By entering the REPL after script execution, the tester gains an interactive session with the browser in whatever state the script left it. This is particularly powerful when combined with a script that intentionally stops at a specific point, creating an ad-hoc breakpoint for investigation.

Related Pages

Implemented By

• Implementation:Getgauge_Taiko_RunFile