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
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 source change to verify no regression before running heavier suites.
4. Do not run bun test:all for a change scoped to one DB — pick the narrowest relevant suite.
5. Use ORCAQ_KEEP_FIXTURES=1 when debugging flaky tests so containers survive after failure.