VESITRail

Imported from VESITRail/VESITRail (AGENTS.md). Install upstream with npx skills add VESITRail/VESITRail. Copyright stays with the author.

[Vitest Docs Index]|root: ./docs/llms/vitest/llms.txt|Consult before writing, modifying, or debugging any .test.ts unit test files in tests/unit/, mock configurations (vi.), fake timers, or assertion matchers. Unit tests must remain pure logic and never touch Prisma, Postgres, or Better Auth.

Unit Testing Rules & Workflow

• Location & Folder Structure: All unit tests reside in tests/unit/ using simple, flat group folders (e.g., tests/unit/onboarding/, tests/unit/admin/, tests/unit/notifications/, tests/unit/pwa/, or root tests/unit/ for standalone utilities). Do NOT create deeply nested mirror paths like tests/unit/src/lib/validations/....
• Existing File Modification Rule: Whenever modifying an existing file that has a corresponding unit test in tests/unit/, you MUST update its unit test to reflect the code changes and verify that all tests pass (pnpm run test:unit). Never leave existing tests broken or out-of-sync.
• New File Creation Rule: Whenever creating a new file containing pure logic (validations, utilities, helpers, algorithms, transformers, monads), assess if a unit test is required. If yes, create a test under tests/unit/<group>/<feature>.test.ts following the exact conventions of existing tests:
  1. Explicit imports from "vitest" (import { describe, it, expect, vi, beforeEach, afterEach } from "vitest").
  2. Always use @/... path aliases for imports (e.g., @/lib/utils, @/lib/validations/...).
  3. Keep test files clean with NO comments.
  4. Pure logic only: NEVER touch Prisma, Postgres, Better Auth, or network I/O.
  5. Test both happy paths and edge cases (empty strings, null/undefined, whitespace trimming, boundary values, invalid schemas).
  6. Always verify changes by running pnpm run test:unit, pnpm run typecheck, and pnpm run format:check.

Integration Testing Rules & Workflow

• Location: All integration tests reside in tests/integration/ using flat files (e.g., tests/integration/auth-guard.test.ts).
• Database: Integration tests run against a real PostgreSQL test database (vesitrail_test).
• Authentication: Uses Better Auth's official testUtils plugin configured in tests/integration/test-auth.ts. Authenticate via authenticateAs(userId) and clear with unauthenticate().
• Test Isolation: Each test file cleans tables in beforeAll and afterAll. Reference seed data is seeded via seedReferenceData(prisma).
• Mocking: External third-party networks (R2/S3, Firebase FCM, SMTP) are mocked in tests/integration/setup.ts. Prisma and Better Auth database interactions are 100% REAL.
• Existing Flow Modification Rule: Whenever modifying an API route (src/app/api/), server action (src/actions/), auth flow, or database lifecycle with a corresponding integration test in tests/integration/, you MUST update the integration test to reflect the behavioral change and verify that tests pass (pnpm run test:integration). Never leave integration tests broken or out-of-sync.
• New Feature / Flow Creation Rule: Whenever creating a new API endpoint, server action, or multi-step database workflow, assess if an integration test is required. If yes, create or update a test under tests/integration/<feature>.test.ts using real PostgreSQL DB operations and Better Auth authenticateAs().
• Commands:
  • pnpm run test:unit (Unit tests only)
  • pnpm run test:integration (Integration tests only)
  • pnpm run test (All tests: unit and integration)
• CI: Level 1 (prettier, eslint, typecheck, unit-tests) must pass before Level 2 (verify-build and integration-tests in parallel).

[Better Auth Docs Index]|root: ./docs/llms/better-auth/llms.txt|Consult before writing, modifying, or debugging any authentication logic, server session validation, Google OAuth flows, or Better Auth client/server configurations. Server session checks must always use auth.api.getSession with incoming headers, and @ves.ac.in domain restriction must be preserved.

User Documentation Synchronization Rules

Whenever modifying, adding, or refactoring features in the codebase:

• Student Guide Synchronization: Whenever any changes affecting student-facing features, onboarding flows, concession applications, renewals, address change workflows, table columns/filters, profile settings, or status lifecycles are made, you MUST update docs/STUDENT_USER_GUIDE.md to maintain 100% accuracy with the codebase.
• Admin Guide Synchronization: Whenever any changes affecting admin-facing features, booklet management, concession review, approval/issuance workflows, anchor calibration, overlay PDF generation, or student management are made, you MUST update docs/ADMIN_USER_GUIDE.md to reflect those changes accurately.
• Zero Speculation / 100% Codebase Accuracy: Documentation must never contain speculative placeholders or assumed labels (e.g., "to be confirmed against the live app"). All steps, button labels, modal titles, routes, and status meanings must precisely match the implementation in the codebase.