OrcaQ Testing — Agent Skill Skill

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

Never run test:api or test:e2e when fixtures are already up — use the :raw variant to avoid double-provisioning.
Never start all fixtures to test a single DB — use the matching profile.
Always run bun test:unit after any source change to verify no regression before running heavier suites.
Do not run bun test:all for a change scoped to one DB — pick the narrowest relevant suite.
Use ORCAQ_KEEP_FIXTURES=1 when debugging flaky tests so containers survive after failure.

Agent Skills: OrcaQ Testing — Agent Skill

Install this agent skill to your local

Skill Files