Encore OS — Documentation

Document Type: PRD
Product: TestSprite integration for Encore 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 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

TestSprite Setup and Usage – setup, runbooks, troubleshooting
TestSprite MCP – Installation
TestSprite – First MCP Test
Testing Documentation – test pyramid, Vitest, Playwright, RLS

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 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.

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 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.

​1. Overview

​1.1 Purpose

​1.2 Scope

​1.3 References

​2. Goals and Success Criteria

​2.1 Goals

​2.2 Success Criteria

​3. User Personas and Use Cases

​3.1 Personas

​3.2 Use Cases

​4. Functional Requirements

​4.1 Configuration and Bootstrap

​4.2 Test Plan Generation

​4.3 Test Execution

​4.4 Reports and Follow-up

​4.5 Application and Environment

​5. Non-Functional Requirements

​5.1 Security and Compliance

​5.2 Usability and Documentation

​5.3 Compatibility and Dependencies

​6. User Flows (High Level)

​6.1 First-Time Setup

​6.2 Subsequent Frontend Test Run (with login)

​6.3 Production-Mode Full Run

​7. Out of Scope (Current Phase)

​8. Dependencies and Constraints

​8.1 Dependencies

​8.2 Constraints

​9. Open Questions and Future Work

​10. Approval and Revision History