Config-driven tests

Introduction

Config-driven tests let you run browser flows from a config file without writing test code. You define steps (navigate, type, click) in a simple text file; CSTesting runs them in the browser and produces a report. Each section in the config becomes one test case in the report.

This is useful when you want to run or share flows quickly, when non-developers need to define tests, or when you want to keep flows in a single file that can be edited without touching code.

You will learn

What config-driven tests are and when to use them
The config file format (syntax and options)
How to run a config file from the command line
How to run a config file from code
How the HTML report works for config runs
Locator syntax you can use in config

What are config-driven tests?

No test code — You write a .conf (or .config) file with one step per line.
Browser automation — CSTesting opens Chrome/Chromium, runs each step in order (goto, type into inputs, click), and stops on the first failure in a test case.
One test case per section — Lines starting with # start a new test case; all following steps belong to it until the next #. The report shows one row per test case with expandable steps.
Same report as code tests — After the run, an HTML report is written to report/report.html with pass/fail, duration, and step list.

Supported steps: goto, type, click, wait, screenshot, doubleClick, rightClick, hover, check, uncheck, select, switchTab, and frame (including nested frames).

Config file format

Use one step per line. Empty lines and lines that don't match any step are ignored.

1. Test case name (section header)

A line that starts with # starts a new test case. The rest of the line is the test case name (used in the report).

# Login Page - Mercury Tours
# My first flow

All following steps (until the next #) belong to this test case. If the file has no # line, all steps form a single test case.

2. Browser mode (headless / headed)

headless=true — Run without a visible browser window (default).
headless=false — Run with a visible browser window.
headed=true — Same as headless=false (visible window).
headed=false — Same as headless=true.

These lines are options, not steps; they don't appear as steps in the report. The last value before a step applies.

headed=true
# Login flow
goto:https://example.com/login

3. Navigate to a URL

goto:https://example.com/login

The browser navigates to the URL. CSTesting waits for the page load (with a timeout) before continuing.

4. Type text into an element

Format: <label>:<locator>=value:<text>

label — Short name for the step (e.g. username, password). Shown in the report.
locator — How to find the element (see Locators in config).
text — The value to type. Everything after =value: is used as the text (so the text can contain spaces or colons).

Examples:

username:#email=value:user@test.com
password:#password=value:secret
name:[name="userName"]=value:mercury

The runner waits for the element to be present (with a timeout), then fills it (focus, set value, fire input/change events). Use this for text inputs and similar fields.

5. Click an element

Format: click=<locator>

Examples:

click=button[type="submit"]
click=[name="submit"]
click=#login-btn

The runner waits for the element, clicks it, then waits for the page load. Use this for submit buttons, links, or any clickable element.

6. Wait (delay)

Format: wait:<ms> or wait:<seconds> (if the number is less than 100, it is treated as seconds).

wait:2000
wait:2

Pauses execution for the given time (2000 ms, or 2 seconds). Use after a click that triggers navigation or dynamic content.

7. Screenshot

Format: screenshot=<path> [fullPage] [element=<locator>]

path — File path to save the image (e.g. screenshot.png).
fullPage — Optional word: capture the full scrollable page.
element=locator — Optional: capture only the element matching the locator.

screenshot=screen.png
screenshot=full.png fullPage
screenshot=hero.png element=#banner

8. Mouse actions

doubleClick=<locator> — Double-click the element.
rightClick=<locator> — Right-click the element.
hover=<locator> — Move the mouse over the element.

The runner waits for the element to be present before performing the action.

9. Checkbox and radio

check=<locator> — Check a checkbox or select a radio button.
uncheck=<locator> — Uncheck a checkbox.

check=#agree
uncheck=#newsletter

10. Select (dropdown)

Format: select=<locator>=value:<value> or select=<locator>=label:<text>

value — Select the option with the given value attribute.
label — Select the option whose visible text matches.

select=#country=value:US
select=#country=label:United States

11. Switch tab/window

Format: switchTab=<index>

Switches to another browser tab by 0-based index (0 = first tab, 1 = second tab). Use after a click that opens a new tab.

click=a[target="_blank"]
wait:1000
switchTab=1

12. Frames and nested frames

Format: frame=<selector> or frame=main

frame=iframe#id — Enter a single iframe. All following steps (click, type, etc.) run inside that frame until you switch again.
frame=selector1,selector2 — Enter nested frames (e.g. outer iframe, then inner iframe). Use comma-separated selectors.
frame=main — Return to the main page. Use this when you are done with frame steps.

goto:https://example.com/page-with-iframe
frame=iframe#content
click=button
field:#field=value:hello
frame=main
click=#back

Full example

login.conf

# Login Page (visible browser)
headed=true
goto:https://example.com/login
username:#email=value:user@test.com
password:#password=value:secret
click=button[type="submit"]

# Second test case - same file
# Simple visit
goto:https://example.com
click=a

First test case: Login Page (visible browser) — headed, goto login page, type username and password, click submit.
Second test case: Simple visit — goto example.com, click the first link.

Running a config file

From the command line

Option 1: Use the run subcommand and pass the config path.

npx cstesting run login.conf
npx cstesting run path/to/my.conf

Option 2: Pass the config file directly (only if the path has extension .conf or .config).

npx cstesting login.conf
npx cstesting flows/demo.config

The CLI looks for the file in the current directory (or the path you give). After the run, the summary is printed (passed/failed/total, duration) and the report path is shown (e.g. report/report.html).

From code

Use runConfigFile to run a config file and get the result (same shape as the normal test run result).

const { runConfigFile } = require('cstesting');

async function main() {
  const result = await runConfigFile('login.conf');
  console.log('Passed:', result.passed, 'Failed:', result.failed, 'Total:', result.total);
  if (result.failed > 0) {
    for (const { test, error } of result.errors) {
      console.log('  Failed:', test, error.message);
    }
  }
}
main();

You can override headless mode from code:

const result = await runConfigFile('login.conf', { headless: false });

If you pass headless, it overrides the headless / headed lines in the config file.

HTML report

After a config run, the same HTML report is written as for code-based tests:

Location — report/report.html (relative to the current working directory; the report/ folder is created if needed).
Content — One row per test case (each # section). You can expand a row to see the list of steps (goto, type username, click submit, etc.). Failed test cases show the error message and stack.
Opening the report — The path is printed in the terminal. Open the file in your browser (e.g. start report\report.html on Windows, open report/report.html on macOS).

Locators in config

Locators in config use the same rules as in code. You can use:

Syntax	Meaning	Example
`#id`	Element with `id="id"`	`#email`
`.class`	Element with that class	`.btn-primary`
`[name="x"]`	Attribute `name="x"`	`[name="userName"]`
`[id="x"]`	Attribute `id="x"`	`[id="submit"]`
Any `[attr="value"]`	Attribute selector	`[data-testid="login"]`
Full CSS selector	Standard CSS	`button[type="submit"]`
XPath	XPath expression	`//button[text()='Submit']`

Examples in config:

username:#email=value:john
password:[name="password"]=value:secret
click=button[type="submit"]
click=[name="submit"]

For type steps, the locator should point to an input or focusable element. For click steps, it should point to a clickable element (button, link, etc.). The runner waits for the element to be present (up to a timeout) before acting.

Summary

Topic	Description
File	Plain text file, one step per line; extension `.conf` or `.config`.
Sections	`# Test case name` starts a new test case; all steps until the next `#` belong to it.
Options	`headless=true/false`, `headed=true/false` — control visible browser.
Steps	`goto:<url>`, `wait:<ms>`, `<label>:<locator>=value:<text>`, `click=` / `doubleClick=` / `rightClick=` / `hover=`, `check=` / `uncheck=`, `select=`, `screenshot=`, `switchTab=`, `frame=`.
Run	`npx cstesting run login.conf` or `npx cstesting login.conf`.
From code	`runConfigFile('login.conf')` or `runConfigFile('login.conf', { headless: false })`.
Report	Same as code tests: `report/report.html` with one row per test case and expandable steps.

Config-driven tests are intended for flows that fit the supported step types. For complex logic, assertions, or API calls, use the regular test runner and write tests in code (see Writing tests and Page Object Model).

Previous « Page Object Model (POM) Next TypeScript »