/testing-orcaq

name: testing-orcaq
description: >
  OrcaQ-specific testing guide. Use when asked to run, debug, or write tests
  for OrcaQ. Covers all bun test:* scripts, fixture profiles, Vitest projects
  (unit / nuxt / integration), and Playwright DB projects. Load BEFORE
  suggesting any test command so the agent uses the correct script and profile.
tools: Read, Edit, Bash, Grep, Glob
category: testing
color: blue
displayName: OrcaQ Testing
applyTo: 'test/**,scripts/test-services/**,.github/workflows/**'

OrcaQ Testing — Agent Skill

> Read `docs/TESTING_GUIDE.md` for the full reference. This skill encodes the > decision rules so you choose the right command without checking every time.

---

1. Decision Tree — Which Command?

Is the test purely logic / no DB / no browser?
  └─ YES → bun test:unit
  └─ NO →
      Is it a Vue component test (nuxt env)?
        └─ YES → bun test:nuxt
        └─ NO →
            Is it an API / server integration test?
              └─ YES →
                  Are fixtures already running?
                    └─ YES → bun test:api:raw
                    └─ NO  → bun test:api          ← auto-provisions + cleans up
              └─ NO →
                  It is a Playwright E2E test.
                  Do you need a specific DB only?
                    └─ YES → bash scripts/test-services/run-tests.sh --fixtures=<profile> -- playwright test --project <db>
                    └─ NO  → bun test:e2e          ← all fixtures, all projects

---

2. npm Script Reference

| Script | What it does | Needs Docker? | | ------------------------ | ----------------------------------------------- | ------------- | | `bun test:all` | All Vitest suites (unit + nuxt + integration) | No | | `bun test:unit` | Unit tests only (`test/unit/`) | No | | `bun test:nuxt` | Nuxt component tests (`test/nuxt/`) | No | | `bun test:api` | Integration tests — auto starts all fixtures | Yes | | `bun test:api:raw` | Integration tests — fixtures must already be up | Yes | | `bun test:e2e` | Playwright — auto starts all fixtures | Yes | | `bun test:e2e:raw` | Playwright — fixtures must already be up | Yes | | `bun test:coverage` | Full coverage report | No | | `bun test:watch` | Watch mode (development) | No | | `bun test:fixtures:up` | Start all Docker fixtures | Yes | | `bun test:fixtures:down` | Stop and remove all Docker fixtures | Yes |

---

3. Vitest Projects

| Project flag | Files | Notes | | ----------------------- | ------------------------------- | ------------------------ | | `--project unit` | `test/unit/**/*.{test,spec}.ts` | Pure logic, no framework | | `--project nuxt` | `test/nuxt/**/*.{test,spec}.ts` | Vue component tests | | `--project integration` | `test/api/**/*.{test,spec}.ts` | Requires all DB fixtures |

Run one file:

bun vitest --run test/unit/core/helpers/myHelper.spec.ts

---

4. Playwright Projects & Fixture Profiles

| Playwright project | Fixture profile to use | | ------------------ | ---------------------------------- | | `common` | `all` | | `postgres` | `postgres` | | `mysql` | `mysql` | | `mariadb` | `mariadb` | | `redis` | `redis` | | `sqlite` | `sqlite` | | `oracle` | manual (no Docker compose profile) |

Run isolated by DB:

bash scripts/test-services/run-tests.sh --fixtures=postgres -- playwright test --project postgres
bash scripts/test-services/run-tests.sh --fixtures=redis   -- playwright test --project redis
bash scripts/test-services/run-tests.sh --fixtures=sqlite  -- playwright test --project sqlite

---

5. Fixture Profile Reference

| Profile | Containers started | | ---------- | ---------------------------- | | `postgres` | PostgreSQL 16 only | | `mysql` | MySQL 8.4 only | | `mariadb` | MariaDB 11.4 only | | `sql` | PostgreSQL + MySQL + MariaDB | | `redis` | Redis 7.4 only | | `mongodb` | MongoDB 7 only | | `sqlite` | File prep only (no Docker) | | `all` | All of the above | | `none` | Nothing |

Manual fixture control:

bash scripts/test-services/start-fixtures.sh --profile <profile>
bash scripts/test-services/stop-fixtures.sh  --profile <profile>

---

6. Key Env Vars

All use `ORCAQ_` prefix. Defaults are set by `start-fixtures.sh` automatically.

ORCAQ_POSTGRES_PORT=5432      ORCAQ_POSTGRES_DATABASE=pagila
ORCAQ_MYSQL_PORT=3306         ORCAQ_MYSQL_DATABASE=sakila
ORCAQ_MARIADB_PORT=3307       ORCAQ_MARIADB_DATABASE=sakila
ORCAQ_REDIS_PORT=6379
ORCAQ_KEEP_FIXTURES=1         # keep containers alive after run
ORCAQ_FIXTURE_PROFILE=all     # override profile via env

---

7. Fast Iteration Pattern

When iterating on integration or E2E tests, start fixtures once and reuse:

bun test:fixtures:up           # 1× — start all containers
bun test:api:raw               # run repeatedly
# or
bun test:e2e:raw               # run repeatedly
bun test:fixtures:down         # done

---

8. Rules the Agent Must Follow

1. **Never run `test:api` or `test:e2e` when fixtures are already up** — use the `:raw` variant to avoid double-provisioning. 2. **Never start all fixtures to test a single DB** — use the matching profile. 3. **Always run `bun test:unit` after any sour