Run Vc Mcp Testing Module

---
name: run-vc-mcp-testing-module
description: Build, launch, smoke-test, and health-check the vc-mcp-testing-module agentic QA tooling repo. Use when asked to run, start, verify, smoke-test, or sanity-check this repo's tooling — env:check, @td() resolution, suite manifest sync, critical-UI-scope, seed dry-run, GraphQL fixture validation — or before running regression.
---

# Run: vc-mcp-testing-module

This repo is **not** a GUI/web/server app. It is an **agentic QA system** for the
Virto Commerce storefront: a collection of Node/tsx CLI scripts plus
agent/skill/command/CSV definitions that drive the *storefront* through MCP
browser servers and the Claude Agent SDK. There is nothing of its own to open in
a browser — the only thing you can launch and observe here is **the tooling**.

So "running this project" means one of two things:

1. **Health-check the tooling** (offline, fast, no secrets) — the `driver.mjs`
   harness below. **This is the agent path. Start here.**
2. **Actually drive the storefront** (regression) — `npm run ci:*` / the
   `/qa-*` slash commands. Needs `ANTHROPIC_API_KEY`, a live `BACK_URL`/`FRONT_URL`,
   and browsers. Costs money and hits a live env — documented but not run by this skill.

> Paths below are relative to the repo root (`<unit>/`). The driver lives at
> `.claude/skills/run-vc-mcp-testing-module/driver.mjs`.

## Prerequisites

- **Node 18+** (verified on `v22.22.0`) and npm (verified `11.14.1`).
- Dependencies installed:
  ```bash
  npm install
  ```
- No OS packages needed for the offline harness — it is pure Node/tsx, no browser,
  no `xvfb`. (Verified on Windows 11 / PowerShell; the driver is cross-platform.)

## Run (agent path) — the offline harness

One command runs every offline-verifiable entry point and prints a pass/fail table:

```bash
node .claude/skills/run-vc-mcp-testing-module/driver.mjs
```

Verified output this session (`8/8 checks OK`, exit 0):

```
▶ env:check … PASS (exit 0) — APPINSIGHTS_RESOURCE_STOREFRONT: SET (len=18)
▶ td-refs … PASS (exit 0) —   No bare GUID/ID literals found. ✓
▶ scope … PASS (exit 0) — [scope:validate] Suites scanned: 103 CSV file(s) under regression\suites/
▶ suites:lint … PASS (exit 0) — [suites:lint] OK (104 suites, 35 selections)
▶ seed:dry-run … PASS (exit 0) — ✅ Seed complete!
▶ b2b-data … PASS (exit 0) — ✓ B2B test-data consistent
▶ graphql:fixtures … PASS (exit 1) — Markdown report: …/reports/graphql-fixtures-validation.md
▶ graphql:labels … PASS (exit 0) — ✅ No findings …
```

(Counts drift as suites are added — they were 103 CSVs / 104 manifest suites / 35
selections this run. The driver asserts exit codes, not counts, so it keeps
passing as the repo grows.)

List checks without running, or run a subset by name substring:

```bash
node .claude/skills/run-vc-mcp-testing-module/driver.mjs --list
node .claude/skills/run-vc-mcp-testing-module/driver.mjs td scope
```

What each check guards (all run from the repo root):

| Check | Underlying command | Asserts |
|-------|--------------------|---------|
| `env:check` | `node get_variables_env.js` | 33 env vars reported SET/EMPTY (exit 0 even if some EMPTY) |
| `td-refs` | `npx tsx scripts/test-data/validate-td-refs.ts` | every `@td()` ref across all suites resolves; no bare GUID/ID literals |
| `scope` | `npx tsx scripts/maintenance/validate-critical-ui-scope.ts` | critical-UI-scope matrix cells point at existing test IDs |
| `suites:lint` | `npx tsx scripts/test-cases/sync-test-suites.ts --check` | `config/test-suites.json` matches CSVs on disk |
| `seed:dry-run` | `node scripts/seed-data/seed-test-data.js catalog --dry-run` | seed planner resolves fixtures, makes no API writes |
| `b2b-data` | `node scripts/seed-data/b2b/validate-b2b-data.mjs` | B2B test-data is consistent (org addresses, user→contact→org→role→membership) |
| `graphql:fixtures` | `npx tsx scripts/graphql/validate-graphql-fixtures.ts` | every `.graphql` fixture validates vs cached schema |
| `graphql:labels` | `npx tsx scripts/graphql/review-graphql-labels.ts <csv>` | runner-native GraphQL CSV has balanced labels |

The driver calls these scripts **directly** rather than via their `npm run`
aliases on purpose — see Gotchas.

**Editing a specific suite?** Most changes here touch CSV suites, not code. Lint
just what you changed instead of the whole driver — the label linter takes a file
**or** a directory:

```bash
npx tsx scripts/graphql/review-graphql-labels.ts regression/suites/Backend/graphql/
```

(Verified: scans 16 files / 300 runner-native cases, exit 0 when balanced.) For
non-GraphQL CSV edits, re-run the `td-refs` and `suites:lint` checks:
`node .claude/skills/run-vc-mcp-testing-module/driver.mjs td-refs suites`.

## Run (real storefront regression) — needs secrets + live env

Not run by this skill (needs API key + live env + browsers, costs money). For
reference, the real entry points are:

- Interactive: the `/qa-regression`, `/qa-smoke`, `/qa-test` slash commands
  (see `.claude/rules/regression.md`).
- Headless CI: `npm run ci:smoke` / `ci:critical` / `ci:full`
  (`ci/run-regression.ts`, Claude Agent SDK). Requires `ANTHROPIC_API_KEY`,
  `BACK_URL`/`FRONT_URL`, and `npx playwright install chromium firefox`.

## Gotchas

- **Several `npm run` aliases are bash-only and break on Windows cmd.exe.**
  `npm run schema:check` fails with `The system cannot find the path specified.`
  because its script ends in `> /dev/null`. The `ci:*` aliases use inline
  `VAR=val cmd` syntax that cmd.exe also can't parse. The driver sidesteps this
  by invoking the scripts directly (`npx tsx scripts/…`) — do the same if you run
  a check by hand on Windows.
- **`graphql:fixtures` exits 1 when a fixture has drifted — that is findings, not a crash.**
  As of this session 66/67 pass; `test-data/graphql/queries/products.graphql`
  reports 2 errors (known schema drift). The driver treats exit 0 **and** 1 as
  "ran OK"; only a missing-file / crash exit is a real failure.
- **The GraphQL schema cache is a local artifact, not committed.**
  `scripts/.graphql-schema.cache.json` (~1.4 MB) is not tracked by git. A fresh
  clone has no cache, so `graphql:fixtures` can't validate until you regenerate it
  with `npx tsx scripts/graphql/validate-graphql-fixtures.ts --refresh` — which needs
  `BACK_URL` in `.env` (live platform). On a machine that already ran against the
  env (like this one) the cache exists and the check runs fully offline.
- **`.env` files are layered and partly gitignored.** `env:check` reads them via
  the layered loader (`.env.defaults` → `.env.${TEST_ENV}` → `.env.local` → `.env`).
  Some vars showing `EMPTY` (e.g. `BROWSERSTACK_*`, 3DS cards) is expected — those
  are optional. `env:check` still exits 0.
- **`.mcp.json` is gitignored** — create it locally before any browser-driven run.
  Irrelevant to the offline harness.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `The system cannot find the path specified.` from `npm run schema:check` | Bash-ism (`> /dev/null`) under Windows. Run the script directly: `node scripts/graphql/refresh-graphql-schema.mjs --dry-run`. |
| `graphql:fixtures` fails with file-not-found / schema cache missing | Regenerate the cache: `npx tsx scripts/graphql/validate-graphql-fixtures.ts --refresh` (needs `BACK_URL` in `.env`). |
| `tsx: not found` / `command not found` | `npm install` — `tsx` is a devDependency. |
| Driver reports a check as `FAIL (exit ERR:ENOENT)` | `node`/`npx` not on PATH, or you ran the driver outside the repo. Run from repo root with Node 18+. |