# zephyr-test-zuellig-agentic

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:
  ```bash
  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

```bash
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.

![Zephyr Scale API Access Tokens](./zephyr-scale-api.png)

Then:

```bash
cp .env.example .env
```

Fill in the values:

```dotenv
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

```bash
./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:

```text
/mcp
```

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

## Daily usage

### Write a test from a Zephyr TC

```text
/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:

```bash
./update-graph.sh
```

### Pull latest frontend + update graph

```bash
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

```bash
npm run typecheck
npm run build
```

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