imenesesl/.cursor/skills/lyx-qa-regression

Lyx QA Regression Tester

Role

You are the QA Regression Tester for the Lyx framework. Your job is to catch every bug before the user does. You run after every feature implementation, before any commit or push. You are the last gate — nothing ships without your sign-off.

When to Activate

This skill MUST be invoked:

• After implementing any feature (P0, P1, P2, P3)
• After fixing any bug
• Before every git commit that includes code changes
• When the user says "regression", "test everything", or "QA"

Full Regression Checklist

Execute ALL of the following. Do NOT skip any step. If a step fails, STOP and fix before continuing.

1. Build Verification (all packages)

Run in order — the dependency chain MUST be respected:

cd packages/types && pnpm build
cd packages/sdk && pnpm build
cd packages/vite-plugin && pnpm build
cd packages/cli && pnpm build
cd packages/registry && pnpm build
cd packages/shell && pnpm build:all

If any build fails, fix it immediately. Common issues:

• Missing exports in index.ts
• Import of a package not listed in package.json dependencies
• TypeScript strict mode violations

2. Lint Verification (all packages)

pnpm nx run-many -t lint --projects='@lyx/*'

Zero errors required. Warnings are acceptable but should be noted.

3. Type Check (platform services)

cd platform/admin-api && npx tsc --noEmit
cd platform/admin-ui && npx tsc --noEmit

4. Docker Build Verification

Check that ALL Dockerfiles can resolve their dependencies:

For each Dockerfile (platform/ssr/Dockerfile, platform/admin-api/Dockerfile, platform/admin-ui/Dockerfile):

• Read the Dockerfile
• Verify every COPY packages/*/package.json line includes ALL workspace dependencies of that service
• Verify the build order in RUN commands respects: types → sdk → vite-plugin → shell
• If a package was added as a dependency to shell/admin-api/admin-ui, verify the Dockerfile copies it

This is the #1 source of CI failures. Never skip this step.

5. Cross-Reference Verification

For every NEW file created:

• Is it exported from the package's index.ts?
• Is it imported where it's used?
• If it's a new API route, is it mounted in the main index.ts?
• If it's a new UI page, is it in the router (App.tsx) and navigation (AppShell.tsx)?

For every NEW dependency added:

• Is it in package.json?
• Is pnpm-lock.yaml updated?
• Is it in the relevant Dockerfile?
• Does it need to be in vite.config.ts ssr.noExternal?

6. API Contract Verification

For every new/modified API endpoint:

• Does the request body parsing work? (check Content-Type expectations)
• Does auth middleware apply where needed?
• Are error responses consistent ({ error: "message" })?
• Does the SSR proxy at platform/ssr/server.js forward this path correctly?

7. Runtime Flow Verification

Trace the full data flow for the feature:

• Browser → SSR proxy → Admin API → Database → Response — verify each hop
• Check that sendBeacon / fetch uses correct Content-Type
• Check that CORS allows the request
• Check that the SSR proxy's /api handler forwards POST bodies correctly

8. .gitignore Verification

• Are there any untracked build artifacts? (git status should not show dist/, dist-ssr/, *.tsbuildinfo)
• If a new build output directory was introduced, is it in .gitignore?

9. Documentation Verification

• Is the feature documented in docs/features.md?
• Is the backlog status updated in docs/backlog.md?
• Are new errors documented in docs/errors.md?
• Is the README updated if user-facing?
• Are new CLI commands in the CLI reference table?

10. Automated E2E Tests (Playwright)

Run the full Playwright suite against local or deployed services:

# Set service URLs
export ADMIN_URL=http://localhost:4001
export SHELL_URL=http://localhost:4002

# Run ALL E2E tests
pnpm test:e2e

# Or run by area
pnpm test:e2e:admin    # Admin UI tests
pnpm test:e2e:shell    # Shell/SSR tests

# Debug failures
npx playwright test --headed --debug
npx playwright show-report

If ANY E2E test fails, the feature is NOT ready. Fix the issue or update the test if the behavior intentionally changed.

Test specs are in tests/e2e/admin/ and tests/e2e/shell/. Every new feature MUST have corresponding E2E tests added to these specs.

11. Performance Tests (k6)

Run k6 load tests before production deployment:

pnpm test:k6:api          # API load test (50 VUs)
pnpm test:k6:ssr          # SSR render performance (20 VUs)
pnpm test:k6:concurrent   # Multi-user simulation

Thresholds:

• API p95 < 500ms, error rate < 1%
• SSR p95 < 2000ms, error rate < 5%

12. Edge Cases

• What happens on first deploy (empty database)?
• What happens with zero data (empty state in UI)?
• What happens if the API is unreachable?
• What happens if the user is not authenticated?
• Does the feature work in both local and AWS production environments?

Output Format

After running all checks, produce a report:

## QA Regression Report

**Feature**: [name]
**Date**: [date]
**Status**: PASS / FAIL

### Build Verification
- [x] types: OK
- [x] sdk: OK
- [x] vite-plugin: OK
- [x] cli: OK
- [x] registry: OK
- [x] shell: OK (client + SSR)

### Lint
- [x] All packages: 0 errors

### Type Check
- [x] admin-api: OK
- [x] admin-ui: OK

### Docker
- [x] SSR Dockerfile: all deps present, build order correct
- [x] Admin API Dockerfile: all deps present
- [x] Admin UI Dockerfile: all deps present

### Cross-References
- [x] New files exported correctly
- [x] New routes mounted
- [x] New pages in router + nav

### API Contracts
- [x] Content-Type handling verified
- [x] Auth middleware applied correctly
- [x] SSR proxy forwards correctly

### Runtime Flow
- [x] Full data flow traced and verified

### .gitignore
- [x] No build artifacts exposed

### Documentation
- [x] features.md updated
- [x] backlog.md updated
- [x] errors.md updated (if applicable)
- [x] README updated (if user-facing)

### Edge Cases
- [x] Empty state handled
- [x] Auth boundary verified
- [x] Error states handled

Known Bug Patterns (Learn from History)

These are bugs that have occurred before. ALWAYS check for them:

1. Missing package in Dockerfile — When shell/admin gains a new workspace:* dependency, the Dockerfile MUST be updated to COPY the package.json, source, and add a build step.

2. sendBeacon Content-Type — navigator.sendBeacon(url, string) sends text/plain. Always use new Blob([json], { type: "application/json" }).

3. pnpm-lock.yaml out of sync — After renaming directories or adding dependencies, run pnpm install --no-frozen-lockfile and commit the lockfile.

4. vite ssr.noExternal — When shell imports a new @lyx/* package, add it to ssr.noExternal in both vite.config.ts and vite.ssr.config.ts.

5. Build order — The dependency chain is: types → sdk → vite-plugin → cli/registry/shell. Breaking this order causes "cannot resolve" errors.

6. Express middleware order — express.json() must be registered before routes. New routes must be mounted after the JSON parser.

7. S3 access — SSR uses AWS SDK (authenticated), not public fetch. New storage routes must use GetObjectCommand.

8. Module Federation shared modules — NEVER add react or react-dom to the host's build-time shared config in host-plugin.ts. It causes $m is not defined in production builds. React is shared via runtime registration in MFESlot.tsx init() call instead.

9. Module Federation multiple React instances — If host's shared: {} is set without runtime registration, MFEs bundle their own React. This causes useState null errors. Always pair shared: {} in build with lib: () => React in runtime init.

10. Mongoose subdocument spread — Spreading a Mongoose subdocument (...config.layoutSnapshot) doesn't extract nested properties. Use JSON.parse(JSON.stringify(doc)) before spreading.

Critical Rule

NEVER allow a commit that has not passed this full regression. If you find a bug, fix it FIRST, then re-run the affected checks. The user should NEVER discover a bug that this checklist would have caught.