Sangeetha-Grantha

Metadata	Value
Status	Folded into TRACK-113
Version	1.2.0
Last Updated	2026-07-09
Author	Antigravity

TRACK-035: Frontend E2E Testing with Playwright

1. Goal

Implement comprehensive end-to-end tests for the Admin Dashboard using Playwright. Focus on the Bulk Import workflow as the primary test scenario, including authentication, batch creation, review workflow, and database verification.

2. Requirements

• Test Framework: Playwright with TypeScript
• Page Object Model: Reusable page objects for navigation and interaction
• Shared Fixtures: Authentication and batch creation reused across tests
• Database Verification: Direct PostgreSQL queries to verify backend state
• API Client: Helper for direct API calls during tests

3. Implementation Plan

3.1 Infrastructure (Completed)

• Playwright configuration (e2e/playwright.config.ts)
• Global setup with backend health check (e2e/global-setup.ts)
• Auth setup fixture (e2e/fixtures/auth.setup.ts)
• Test data constants (e2e/fixtures/test-data.ts)

3.2 Page Objects (Completed)

• Base page class (e2e/pages/base.page.ts)
• Login page (e2e/pages/login.page.ts)
• Bulk Import page (e2e/pages/bulk-import.page.ts)
• Import Review page (e2e/pages/import-review.page.ts)
• Krithi List page (e2e/pages/krithi-list.page.ts)

3.3 Utilities (Completed)

• API client for backend calls (e2e/utils/api-client.ts)
• Database verifier (e2e/fixtures/db-helpers.ts)
• Polling utilities (e2e/utils/polling.ts)
• Log verifier (e2e/utils/log-verifier.ts)

3.4 Test Fixtures (Completed)

• Shared batch fixture (e2e/fixtures/shared-batch.ts)
• Batch reuse across tests working correctly
• Global setup creates batch once, tests reuse via state file

3.5 Test Specs (Completed)

• Happy path tests (e2e/tests/bulk-import-happy-path.spec.ts) - 11 tests
• Database verification tests (e2e/tests/bulk-import-database.spec.ts) - 14 tests
• Error case tests (e2e/tests/bulk-import-error-cases.spec.ts) - 7 tests
• Review workflow tests (e2e/tests/bulk-import-review.spec.ts) - 10 tests

4. Test Results

Latest Run (2026-02-03)

| Status | Count | |——–|——-| | Passed | 22 | | Skipped | 18 | | Failed | 0 | | Total | 40 |

Test Breakdown by Category

Category	Passed	Skipped	Notes
Database State Verification	7	7	Skipped tests require entity resolution completion
Error Cases	7	0	All error handling tests pass
Happy Path	7	4	Skipped tests require pending imports
Review Workflow	3	7	Skipped tests require pending imports

Why Tests Skip (Expected Behavior)

The skipped tests are not failures - they gracefully handle async batch processing:

• Entity resolution phase hasn’t completed yet
• No imported_krithis records exist until scraping finishes
• Batch finalization requires SUCCEEDED status

5. Architecture

e2e/
├── fixtures/
│   ├── auth.setup.ts       # Login and save auth state
│   ├── db-helpers.ts       # Direct PostgreSQL queries
│   ├── shared-batch.ts     # Shared batch fixture for all tests
│   └── test-data.ts        # Test constants and config
├── pages/
│   ├── base.page.ts        # Common page methods
│   ├── bulk-import.page.ts # Bulk import page interactions
│   ├── import-review.page.ts
│   ├── krithi-list.page.ts
│   └── login.page.ts
├── tests/
│   ├── bulk-import-database.spec.ts  # DB state verification
│   ├── bulk-import-error-cases.spec.ts
│   ├── bulk-import-happy-path.spec.ts
│   └── bulk-import-review.spec.ts
├── utils/
│   ├── api-client.ts       # HTTP client for API calls
│   ├── log-verifier.ts     # Log file inspection
│   └── polling.ts          # Async polling utilities
├── global-setup.ts         # Pre-test setup (health check, batch creation)
└── playwright.config.ts    # Playwright configuration

6. Running Tests

# From modules/frontend/sangita-admin-web
bun run test:e2e           # Run all E2E tests
bun run test:e2e:ui        # Run with Playwright UI
bun run test:e2e:debug     # Debug mode

Prerequisites

1. Backend running: mise exec -- cargo run --manifest-path tools/sangita-cli/Cargo.toml -- dev --start-db
2. Frontend running: bun run dev

Clean Run

To start fresh (removes cached batch state):

rm -f e2e/.batch-state.json
bun run test:e2e

7. Issues Fixed

Issue	Fix
Batch created per test instead of once	Moved batch creation to global-setup.ts with state file
DB enum case mismatch (PENDING vs pending)	Updated db-helpers.ts to use lowercase enum values
Audit log column names wrong	Fixed created_at → changed_at, user_id → actor_user_id
Flaky batch visibility test	Added refresh before waiting for batch in list

8. Future Improvements

• CI/CD integration with GitHub Actions
• Parallel test execution (currently serial for shared batch)
• Visual regression testing
• Performance benchmarks for batch processing
• Test data seeding for complete workflow tests

9. Files Changed

• modules/frontend/sangita-admin-web/e2e/**/* - Test framework and specs
• modules/frontend/sangita-admin-web/package.json - Test scripts
• modules/frontend/sangita-admin-web/bun.lock - Dependencies