Automate BDD Tests with Gwirian, Playwright, and a LLM

An AI assistant can read your BDD scenarios from Gwirian, drive a real browser with Playwright, and record pass/fail back to Gwirian—all from your editor. This post walks through the setup and a concrete example.

Three pieces work together: gwirian-cli (terminal access to the Gwirian API), playwright-cli (browser automation from the terminal), and workflow skills (instructions that teach the LLM how to orchestrate both).

Prerequisites

• Node.js >= 18
• A Gwirian account with an API token (from the hosted app or your self-hosted instance)
• An AI assistant or editor that can run terminal commands

Install and configure gwirian-cli

Install the CLI

npm install -g @acmada/gwirian-cli

Configure

Get your API token from Gwirian (workspace → API token), then:

gwirian auth

The CLI uses https://app.gwirian.com by default. To use a self-hosted instance, run gwirian config set base-url <url>. Config is stored in ~/.config/gwirian-cli/config.json (or $XDG_CONFIG_HOME/gwirian-cli/config.json).

Verify

gwirian projects list

You should see your workspace projects.

Install the skill

So your AI assistant (Cursor or Claude Code) knows how to use the CLI:

gwirian install --skills

This copies the skill into .cursor/skills/gwirian-cli and .claude/skills/gwirian-cli in the current directory. Use --target cursor or --target claude to install for one client only, and --global (or -g) to install in your home directory (~/.cursor/skills/gwirian-cli, ~/.claude/skills/gwirian-cli).

Install and configure playwright-cli

Playwright CLI lets the LLM control a real browser from the terminal (open, goto, snapshot, click, fill, etc.).

Install the CLI

npm install -g @playwright/cli

Configure

Install the browser (required for automation):

playwright-cli install-browser

Verify

playwright-cli open https://app.gwirian.com
playwright-cli snapshot
playwright-cli close

You should see a snapshot of the page; close shuts the browser.

Install the skill

So your AI assistant can drive the browser from the terminal:

playwright-cli install --skills

This copies the skill into .cursor/skills/playwright-cli and .claude/skills/playwright-cli in the current directory. Use --target cursor or --target claude for one client only, and --global to install in your home directory if your version supports it.

With gwirian-cli and playwright-cli configured, the LLM can talk to Gwirian from the terminal (e.g. gwirian --json projects list, gwirian scenario-executions create ... --status passed) and drive the browser—no MCP server required.

Provide workflow skills to the LLM

A skill is a set of instructions (often in a SKILL.md file) that teaches the LLM a workflow: when to use which tools and in what order. For “run my BDD scenarios in the browser and record results,” you need three kinds of skills:

1. gwirian-cli — Install with gwirian install --skills (see above); teaches the LLM how to call the CLI (projects, features, scenarios, scenario-executions).
2. playwright-cli — Install with playwright-cli install --skills (see above); documents the browser commands (open, goto, snapshot, click, fill, etc.).
3. Your own orchestration skill — You must create a skill that tells the LLM how to combine both tools: resolve projects/features/scenarios via gwirian-cli, run each scenario in the browser with playwright-cli (login, navigate, perform given/when/then steps), and record the result with gwirian scenario-executions create. Without this orchestration, the LLM has the building blocks but not the workflow.

You can use our orchestration skill as a starting point. The one we use for Gwirian’s own tests is available here: gwirian-feature-tests. Copy or adapt it into your project (e.g. .cursor/skills/gwirian-feature-tests/ or a name of your choice). Once the LLM can see the gwirian-cli skill, the playwright-cli skill, and your orchestration skill, it can run tests when you ask (e.g. “Run the Product Search scenarios on production”).

Example: testing an e-commerce project

Assume you have a Gwirian project where you define BDD scenarios for an e-commerce app (e.g. “Product Search,” “Shopping Cart,” “Checkout”). The app runs locally or in production; the LLM will open it in a browser and follow the scenarios.

Project setup in Gwirian

Create the project in the Gwirian UI if needed. In the project Settings (or when creating the project), fill in the Context field: environments and URLs, test accounts, and how to log in. The assistant will read this context when it fetches the project via gwirian-cli, so it can open the right URL, authenticate, and map scenario steps to your UI. Example context to enter in Gwirian:

Environments: Local http://localhost:3000, staging https://staging.shop.example.com, production https://shop.example.com. To log in on any environment, go to /login, enter the test user email [email protected], click “Send magic link,” then enter the code from the email when prompted.

Then add features and scenarios via the CLI. Example (replace project id 1 and feature id 7 with your own, or get them from gwirian projects list and gwirian features list <project-id>):

gwirian features create 1 --title "Product Search" --description "Search and filter products"
gwirian scenarios create 1 7 --title "Search by keyword" \
  --given "I am on the products page" \
  --when "I type 'wireless headphones' in the search bar" \
  --then "I see only products matching 'wireless headphones'"

You can add more scenarios (e.g. “No results for query,” “Filter by category”) the same way.

Ask the LLM to run the tests

The assistant uses the project context you entered in Gwirian (see above) when it fetches the project with gwirian projects list or gwirian projects show <id> (use --json so the response includes the project context). Just ask to run the scenarios, for example:

• “Run the two scenarios Search by keyword and Filter by category in the Product Search feature on production.”
• “Run all scenarios for features tagged smoke on the local environment.”
• “Run all scenarios in the Shopping Cart feature on staging.”

The assistant will (if the skills are configured):

1. List your Gwirian projects with gwirian projects list (or --json) and find the one that holds the specs.
2. List features and scenarios with gwirian features list and gwirian scenarios list, find “Product Search,” and get its scenario ids.
3. Ask you which environment to use (local http://localhost:3000 or production https://app.gwirian.com) if not specified.
4. Open the browser with playwright-cli, log in if needed, go to the right project, and for each scenario perform the steps (navigate, fill, click).
5. For each scenario, record the result with gwirian scenario-executions create <project-id> <feature-id> <scenario-id> --status passed (or failed).

What happens under the hood

Rough sequence:

1. gwirian-cli — gwirian projects list, gwirian features list <project-id>, gwirian scenarios list <project-id> <feature-id> (use --json if the LLM parses output) to get the ordered list of scenarios.
2. playwright-cli — open, goto <base>/session/new, snapshot, fill (email), click (Get code), then you provide the magic link code; then goto project, and for each scenario: snapshot, click/fill/type using refs from the snapshot.
3. gwirian-cli — After each scenario run, gwirian scenario-executions create <project-id> <feature-id> <scenario-id> --status passed (or failed).

The gwirian-feature-tests skill encodes the exact flow (login, navigation, mapping scenario titles to UI actions, order of scenarios).

Results

The LLM prints a short summary table: feature name, scenario title, status (Passed/Failed). The executions appear in Gwirian: project → feature → scenario → execution history. You get a real run in a real browser and a clear record in your test management tool.

Summary

• gwirian-cli — Install the CLI (npm install -g @acmada/gwirian-cli), configure with gwirian auth, then install the skill with gwirian install --skills (optionally --global or --target cursor/claude).
• playwright-cli — Install the CLI (npm install -g @playwright/cli), install the browser (playwright-cli install-browser), then install the skill with playwright-cli install --skills. The LLM uses it to drive the browser (open, goto, snapshot, click, fill, etc.).
• Workflow skills — Install the gwirian-cli and playwright-cli skills (see above). You must add your own orchestration skill that tells the LLM how to combine both (fetch scenarios from Gwirian, run them in the browser, record results). Use our gwirian-feature-tests skill as a starting point. No MCP server needed; if you prefer MCP, see our post on the Gwirian MCP server.

Together, they let you say “run my Product Search scenarios on production” and get browser-based execution with results stored in Gwirian. For more on Gwirian’s features, see the Features page.