Zephyr

Agentic test generation for eZRX+ — converts Zephyr Scale test cases into Playwright integration tests using Claude Code or Codex.

What this repo does

1. Runs a Zephyr Scale MCP server to fetch test cases and steps.
2. Runs a code-review-graph MCP server to index the frontend codebase for token-efficient context loading.
3. Provides a /write-integration-test command that Claude Code reads from .claude/commands/ — no global config needed.

All generated tests are written into datasource/frontend/ (a local clone of the frontend repo). Nothing is installed or modified in the real frontend repo.

Requirements

• Node.js 20.6 or later
• Python 3.10 or later with code-review-graph installed:

  pip install code-review-graph
  

• Claude Code CLI or Codex CLI
• Git Bash or WSL on Windows

Setup (first time)

1. Clone and enter the repo

git clone <repository-url>
cd zephyr-test-zuellig-agentic

2. Create .env

Get a Zephyr Scale API token:

1. Sign in to Jira.
2. Open profile menu → Zephyr Scale API Access Tokens.
3. Create a token and copy it.

Then:

cp .env.example .env

Fill in the values:

ZEPHYR_API_TOKEN=your-zephyr-api-token
FRONTEND_REPO_URL=https://github.com/your-org/frontend.git

.env is gitignored — do not commit your token.

3. Run setup

./setup.sh

This will:

• Clone FRONTEND_REPO_URL into datasource/frontend/
• Build the code-review-graph index for the frontend
• Build the Zephyr MCP server from source
• Generate .mcp.json for Claude Code project-level MCP

4. Open in Claude Code

Open the zephyr-test-zuellig-agentic/ folder in Claude Code (not datasource/frontend/). Claude Code auto-loads .mcp.json — both MCP servers start automatically.

Verify:

/mcp

Both zephyr and code-review-graph should show as connected.

Daily usage

Write a test from a Zephyr TC

/write-integration-test EZRX-T10000

Claude will:

1. Fetch the TC name, objective, and steps from Zephyr
2. Search the codebase graph for relevant page objects and similar specs
3. Generate the spec file (and any new page object methods / locators needed)
4. Run tsc --noEmit and playwright test --list to verify

Generated files land in datasource/frontend/integration_test/. Commit and push from there.

Update the graph after local changes

When you edit files in datasource/frontend/ and want Claude to see the changes:

./update-graph.sh

Pull latest frontend + update graph

git -C datasource/frontend pull --ff-only
./update-graph.sh

Troubleshooting

.mcp.json missing — run ./setup.sh to regenerate it.

datasource/frontend missing — run ./setup.sh to clone the frontend repo.

MCP not connected — restart Claude Code after setup.sh completes, then check /mcp.

ZEPHYR_API_TOKEN error — make sure .env exists and ZEPHYR_API_TOKEN is set.

code-review-graph not found — run pip install code-review-graph.

Development

npm run typecheck
npm run build

Zephyr MCP source is in src/; compiled output goes to build/.