TestSprite setup and usage

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.

​

Prerequisites

• Node.js >= 22
• TestSprite account (free tier available)
• API key from TestSprite Dashboard → Settings → API Keys

​

1. Install TestSprite MCP in Cursor

1. Open Cursor Settings (e.g. Ctrl+Shift+J / Cmd+Shift+J).
2. Go to Tools & Integration → Add custom MCP (or edit existing MCP config).
3. Add or update a TestSprite MCP entry with your real API key:
   • Replace YOUR_TESTSPRITE_API_KEY in the env.API_KEY field with your key from the dashboard.
   • Do not commit real API keys. Use a local override or Cursor’s env/secrets if available.
4. Restart Cursor if needed; confirm the TestSprite MCP server shows as connected (green).

​

2. Prepare the app

• Frontend (development): From repo root run npm run dev (app on port 8080). TestSprite will limit to 15 high-priority tests in dev mode.
• Frontend (production, recommended for stable runs): Run npm run build && npm run preview. Confirm the app loads at http://localhost:8080. When calling testsprite_generate_code_and_execute, set serverMode: "production" so all tests run and the app is more stable (no HMR during login).
• Backend/API: If testing APIs, ensure your backend is running and reachable (e.g. Supabase + edge functions per project setup).
• Have a test user (e.g. from .env.local / Lovable secrets) for login if testing authenticated flows.

​

3. Run tests with TestSprite

1. Open a new Cursor Chat.
2. Type: “Can you test this project with TestSprite?”
3. Optionally drag the project folder (or a subfolder) into the chat.
4. When the Testing Configuration page opens in the browser, set:
   • Testing type: Frontend (UI) and/or Backend (APIs).
   • Scope: Code Diff (recent changes) or Codebase (full).
   • Test credentials: e.g. TEST_USER_ADMIN_EMAIL / TEST_USER_ADMIN_PASSWORD if your app requires login.
   • Application URLs: e.g. Frontend http://localhost:8080, Backend URL if applicable.
   • PRD: Upload an existing product/requirements doc (draft is fine); TestSprite will normalize it.
5. Let the assistant run the TestSprite tools; it will generate a test plan, run tests in the cloud, and produce reports.

​

4. Where results go

• testsprite_tests/ in the project (folder is gitignored):
  • testsprite-mcp-test-report.md or TestSprite_MCP_Test_Report.md – human-readable report.
  • tmp/test_results.json, tmp/config.json, generated test files (e.g. TC001_*.py).
• Use the report to see pass rate, failures, and suggested fixes.

​

5. Ensure everything is running (checklist)

1. Node.js: Run node --version — must be >= 22 (TestSprite requirement).
2. App: Run npm run dev (development) or npm run build && npm run preview (production). Confirm the app loads at http://localhost:8080. For production mode, tell the assistant to use serverMode: "production" when calling generate_code_and_execute.
3. MCP: In Cursor Settings → MCP, confirm TestSprite shows connected (green). Set API_KEY in the TestSprite server config. Use .cursor/mcp.json.example as a template and keep API keys environment-based. If your API key was ever committed, rotate it at TestSprite Dashboard → Settings → API Keys.
4. Cursor sandbox: Verify Chat → Auto-Run → Auto-Run Mode is Ask Every Time or Run Everything (see Cursor Sandbox Mode).
5. First-time only: If testsprite_tests/ does not exist or is empty, run the bootstrap step (e.g. in Cursor chat: “Can you test this project with TestSprite?” and complete the browser config). This creates testsprite_tests/tmp/config.json and later standard_prd.json and tmp/code_summary.yaml.

​

Before execute (important):

• In Cursor chat, run the full TestSprite flow so that the assistant calls testsprite_generate_frontend_test_plan (with your project path and needLogin: true). After that, testsprite_frontend_test_plan.json should appear under testsprite_tests/.
• Then run testsprite_generate_code_and_execute (or the CLI command the assistant suggests). Do not run execute until the test plan file exists.

• testsprite_tests/tmp/config.json
• testsprite_tests/standard_prd.json
• testsprite_tests/testsprite_frontend_test_plan.json

​

Quick reference

• Get API key: Dashboard → Settings → API Keys
• Set key in Cursor: Use .cursor/mcp.json.example template and set env.API_KEY locally in Cursor MCP config
• Node.js: Run node --version — must be >= 22
• Start app (dev): npm run dev (port 8080); tests limited to 15 in dev mode
• Start app (prod): npm run build && npm run preview; use serverMode: "production" for full runs
• Auth instruction: Pass additionalInstruction with wait-after-Sign-In text (see §3) or use testsprite_tests/additional_instruction_auth.txt
• Trigger test: In chat: “Can you test this project with TestSprite?”
• Configure: Browser form: type, scope, credentials, URLs, PRD

​

Troubleshooting