Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
Document Type: PRD
Product: TestSprite integration for Encore Health OS
Version: 1.0.0
Last Updated: 2026-03-10
Status: Draft
1. Overview
1.1 Purpose
This PRD defines the product requirements for TestSprite integration within the Encore Health OS platform. TestSprite provides AI-powered autonomous testing (frontend E2E and backend API) via an MCP (Model Context Protocol) server in Cursor, enabling developers and AI assistants to generate test plans, execute tests in the cloud, and consume structured reports without maintaining large hand-written E2E suites for every change.
1.2 Scope
- In scope: Use of TestSprite MCP in Cursor for frontend (UI) and backend (API) test generation and execution; configuration, workflows, and consumption of test reports for this repository.
- Out of scope: TestSprite’s internal product roadmap; replacement of existing Vitest/Playwright/RLS test suites; CI/CD integration (future phase).
1.3 References
2. Goals and Success Criteria
2.1 Goals
| Goal | Description |
|---|
| Faster feedback | Enable AI-assisted and developer-triggered autonomous test runs (frontend and backend) without writing full E2E test code upfront. |
| Coverage discovery | Use AI-generated test plans to discover high-value scenarios and gaps relative to product behavior. |
| Regression signal | Get a clear pass/fail and failure report after changes to prioritize fixes. |
| Single workflow | Align “run tests” with the existing Cursor + MCP workflow (e.g. “Can you test this project with TestSprite?”). |
2.2 Success Criteria
| Criterion | Measure |
|---|
| Setup completion | A new developer with Node ≥22 and a TestSprite account can run a first TestSprite test within one session using TESTSPRITE.md. |
| Run reliability | With app running (dev or production) and correct auth instructions, TestSprite runs complete and produce a report (pass/fail and failure details). |
| Actionable reports | Reports (e.g. testsprite-mcp-test-report.md / TestSprite_MCP_Test_Report.md) are sufficient for an AI or developer to identify failing flows and apply fixes. |
| Security | API keys and credentials are not committed; testsprite_tests/ remains gitignored; key rotation is documented. |
3. User Personas and Use Cases
3.1 Personas
| Persona | Description | Primary need |
|---|
| Developer | Engineer working in Cursor on Encore Health OS | Run autonomous tests after changes; get a quick regression signal. |
| AI assistant | Cursor AI using TestSprite MCP tools | Bootstrap config, generate test plans, execute tests, and interpret reports to suggest or apply fixes. |
| QA / release | Validator before release | Run full (e.g. production-mode) TestSprite suite and use report for go/no-go. |
3.2 Use Cases
| ID | Use case | Trigger | Outcome |
|---|
| UC-1 | First-time setup | New machine or new contributor | TestSprite MCP configured; first bootstrap and test run successful. |
| UC-2 | Ad-hoc frontend test run | Developer or AI: “Can you test this project with TestSprite?” | Test plan generated; tests executed; report saved under testsprite_tests/. |
| UC-3 | Frontend test with auth | Same as UC-2 with login required | Auth credentials and additionalInstruction (e.g. Supabase redirect wait) applied; login flow tested. |
| UC-4 | Production-mode full run | Developer wants full test set, stable environment | App run with npm run build && npm run preview; serverMode: "production" used; full test set executed. |
| UC-5 | Backend/API test run | User selects backend testing in config | Backend test plan generated and executed; API test results in report. |
| UC-6 | Fix from report | After a failed run | Developer or AI uses report to fix failures; optionally re-runs tests to confirm. |
| UC-7 | Rerun subset | Re-run specific test IDs | testsprite_rerun_tests (or equivalent) used with selected test IDs; updated report. |
4. Functional Requirements
4.1 Configuration and Bootstrap
| ID | Requirement | Priority | | |
|---|
| FR-1 | Project MUST be bootstrapped once via TestSprite (e.g. testsprite_bootstrap) when no config exists; bootstrap MUST NOT be re-run when config already exists. | Must | | |
| FR-2 | Bootstrap SHALL accept: project path, local port (e.g. 8080), pathname (optional), type (frontend | backend), test scope (codebase | diff). | Must |
| FR-3 | Generated config (e.g. testsprite_tests/tmp/config.json) SHALL be gitignored. | Must | | |
| FR-4 | API key SHALL be provided via MCP env (e.g. env.API_KEY); SHALL NOT be committed to the repo. | Must | | |
4.2 Test Plan Generation
| ID | Requirement | Priority |
|---|
| FR-5 | Frontend test plan SHALL be generatable via MCP (e.g. testsprite_generate_frontend_test_plan) with project path and needLogin. | Must |
| FR-6 | Backend test plan SHALL be generatable via MCP (e.g. testsprite_generate_backend_test_plan) with project path. | Should |
| FR-7 | Test plan output (e.g. testsprite_tests/testsprite_frontend_test_plan.json) SHALL exist before execute is called; execute SHALL depend on it. | Must |
| FR-8 | A standardized PRD MAY be generated (e.g. testsprite_generate_standardized_prd) for TestSprite to normalize requirements; optional upload in config. | Could |
4.3 Test Execution
| ID | Requirement | Priority |
|---|
| FR-9 | Execute SHALL require: local app running (dev or production), existing test plan, project path and name. | Must |
| FR-10 | Execute SHALL support serverMode: development (limited frontend tests, e.g. 15) or production (full set). | Must |
| FR-11 | Execute SHALL accept optional additionalInstruction (e.g. Supabase auth redirect wait) for stable auth flows. | Must |
| FR-12 | Execute SHALL support optional testIds to run a subset of the plan. | Should |
| FR-13 | Execute SHALL produce a human-readable report (e.g. markdown) and machine-readable artifacts under testsprite_tests/. | Must |
4.4 Reports and Follow-up
| ID | Requirement | Priority |
|---|
| FR-14 | Report SHALL include pass/fail summary and failure details sufficient to locate and fix issues. | Must |
| FR-15 | User MAY request “fix the codebase based on TestSprite results”; AI SHALL use report and codebase to propose or apply fixes. | Should |
| FR-16 | User MAY open TestSprite test result dashboard (e.g. testsprite_open_test_result_dashboard) when supported. | Could |
| FR-17 | User MAY check account info (e.g. testsprite_check_account_info) for quota/limits. | Could |
4.5 Application and Environment
| ID | Requirement | Priority |
|---|
| FR-18 | Frontend tests SHALL run against a running app at a configured URL (e.g. http://localhost:8080). | Must |
| FR-19 | When login is required, test credentials (e.g. from .env.local or Lovable secrets) SHALL be configurable in TestSprite config; credentials SHALL NOT be committed. | Must |
| FR-20 | Backend/API tests SHALL run against a running backend (e.g. Supabase + edge functions) when backend type is selected. | Should |
5. Non-Functional Requirements
5.1 Security and Compliance
| ID | Requirement | Priority |
|---|
| NFR-1 | TestSprite API key SHALL be stored only in local MCP config or env; SHALL NOT appear in repo or logs. | Must |
| NFR-2 | If an API key is ever committed, it SHALL be rotated immediately via TestSprite Dashboard. | Must |
| NFR-3 | Generated artifacts under testsprite_tests/ (config, reports, plans) SHALL remain in .gitignore to avoid leaking credentials or internal test data. | Must |
| NFR-4 | Test credentials (e.g. test user email/password) SHALL be provided via secure env or secrets, not hardcoded. | Must |
5.2 Usability and Documentation
| ID | Requirement | Priority |
|---|
| NFR-5 | A single setup doc (TESTSPRITE.md) SHALL cover: prerequisites, MCP install, app preparation, run workflow, auth instruction, result locations, troubleshooting. | Must |
| NFR-6 | Checklist “Before running TestSprite” SHALL be documented (Node ≥22, app running, MCP connected, sandbox mode, bootstrap when needed, test plan present). | Must |
| NFR-7 | Auth-specific instruction (e.g. 8–10 second wait after Sign In for Supabase redirect) SHALL be documented and passable as additionalInstruction. | Must |
5.3 Compatibility and Dependencies
| ID | Requirement | Priority |
|---|
| NFR-8 | Node.js version SHALL be ≥22 for TestSprite tooling. | Must |
| NFR-9 | Cursor Auto-Run (sandbox) SHALL be set to “Ask Every time” or “Run Everything” for full TestSprite behavior. | Must |
| NFR-10 | Default app port SHALL be 8080 (Vite dev/preview); bootstrap and docs SHALL reflect this. | Must |
6. User Flows (High Level)
6.1 First-Time Setup
- Developer installs Node ≥22 and creates TestSprite account.
- Developer adds TestSprite MCP in Cursor with API key in env.
- Developer runs “Can you test this project with TestSprite?” (or equivalent).
- AI runs bootstrap (no config yet); user completes browser config (type, scope, credentials, URLs, optional PRD).
- Config and (after plan generation) test plan files appear under
testsprite_tests/.
- First execute produces a report.
6.2 Subsequent Frontend Test Run (with login)
- Developer starts app:
npm run dev or npm run build && npm run preview.
- Developer (or AI) triggers TestSprite test run with auth credentials and
additionalInstruction for Supabase redirect.
- AI generates frontend test plan (if needed) then calls generate_code_and_execute.
- TestSprite runs tests; report is written to
testsprite_tests/.
- Developer or AI reads report and optionally applies fixes and re-runs.
6.3 Production-Mode Full Run
- Developer runs
npm run build && npm run preview and confirms app at http://localhost:8080.
- Developer asks AI to run TestSprite with
serverMode: "production".
- Full test set runs; report is generated.
- Report used for release sign-off or fix list.
7. Out of Scope (Current Phase)
- CI/CD integration (e.g. GitHub Actions calling TestSprite).
- Replacing or merging existing Vitest/Playwright/RLS suites with TestSprite.
- TestSprite product features not exposed via current MCP tools.
- Commitment to a specific TestSprite pricing tier or quota.
8. Dependencies and Constraints
8.1 Dependencies
- TestSprite cloud service and MCP server availability.
- Cursor IDE with MCP support.
- Node.js ≥22.
- Running Encore Health OS frontend (and optionally backend) during test execution.
- TestSprite account and valid API key.
8.2 Constraints
- Test plan file must exist before execute (generated in same flow or previous run).
- Auth flows require explicit wait instruction for async redirect (Supabase).
- Dev mode limits frontend tests (e.g. 15) to avoid overload; production mode for full set.
testsprite_tests/ is gitignored; no in-repo history of reports or config.
9. Open Questions and Future Work
| Topic | Question / Future work |
|---|
| CI integration | How to trigger TestSprite from GitHub Actions (or other CI) with secrets and running app? |
| PRD normalization | When to use testsprite_generate_standardized_prd and how to maintain a project PRD for TestSprite? |
| Backend coverage | Which backend/API surfaces are in scope for TestSprite backend plans? |
| Quota and limits | How to surface TestSprite account/quota (e.g. testsprite_check_account_info) in runbooks? |
| Report retention | Policy for local report retention and cleanup under testsprite_tests/. |
10. Approval and Revision History
| Version | Date | Author | Changes |
|---|
| 1.0.0 | 2026-03-10 | — | Initial PRD for TestSprite integration. |
See also: TESTSPRITE.md for setup and runbooks; README.md for the testing pyramid and other test types.
