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

# TestSprite setup and usage

> Purpose: Run AI-powered autonomous tests (frontend E2E and backend API) via the TestSprite MCP server in Cursor.

**Purpose:** Run AI-powered autonomous tests (frontend E2E and backend API) via the TestSprite MCP server in Cursor.

**Docs:** [TestSprite MCP – Installation](https://docs.testsprite.com/mcp/getting-started/installation), [First MCP Test](https://docs.testsprite.com/mcp/getting-started/first-test).

***

## Prerequisites

* Node.js >= 22
* [TestSprite account](https://www.testsprite.com/auth/cognito/sign-up) (free tier available)
* API key from [TestSprite Dashboard](https://www.testsprite.com/dashboard) → Settings → API Keys

***

## 1. Install TestSprite MCP in Cursor

TestSprite is provided as an example entry in `.cursor/mcp.json.example`. Configure it locally with your own API key:

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

**Cursor sandbox:** For full TestSprite behavior, set **Chat** → **Auto-Run** → **Auto-Run Mode** to **Ask Every time** or **Run Everything** (see [Cursor Sandbox Mode](https://docs.testsprite.com/mcp/getting-started/installation#cursor-sandbox-mode-configuration)).

***

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

**Auth and `additionalInstruction`:** Our app uses Supabase auth with an async redirect after Sign In. To avoid most login-related failures, when the assistant calls **testsprite\_generate\_code\_and\_execute**, ask it to pass `additionalInstruction` with: *"After clicking Sign In, wait at least 8 seconds for the Supabase auth redirect to complete before interacting with the page again. The app redirects to /dashboard after successful login. Do NOT retry login if the URL still shows /auth within the first 10 seconds — the redirect is async."* A copy of this text is in `testsprite_tests/additional_instruction_auth.txt` (inside the gitignored `testsprite_tests/` folder) for reference.

***

## 4. Where results go

After a run, look for:

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

To ask for automatic fixes: *"Please fix the codebase based on TestSprite testing results."*

***

## 5. Ensure everything is running (checklist)

Before running TestSprite, confirm the following.

**Before running TestSprite:**

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](https://www.testsprite.com/dashboard/settings/apikey).
4. **Cursor sandbox:** Verify **Chat** → **Auto-Run** → **Auto-Run Mode** is **Ask Every Time** or **Run Everything** (see [Cursor Sandbox Mode](https://docs.testsprite.com/mcp/getting-started/installation#cursor-sandbox-mode-configuration)).
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):

The TestSprite CLI expects `testsprite_tests/testsprite_frontend_test_plan.json`. That file is created when the Cursor assistant calls the **generate frontend test plan** MCP tool (e.g. as part of "Can you test this project with TestSprite?"). So:

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

**Optional verification:**

Before execute, check that these exist:

* `testsprite_tests/tmp/config.json`
* `testsprite_tests/standard_prd.json`
* `testsprite_tests/testsprite_frontend_test_plan.json`

**Note:** `testsprite_tests/` is in `.gitignore` so generated reports and config are not committed and API keys/credentials stay out of the repo.

***

## Quick reference

* **Get API key:** [Dashboard](https://www.testsprite.com/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

| Issue                                             | Fix                                                                                                                                                                                                                                              |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **MCP server not connecting**                     | Check Cursor Settings → Tools & Integration (or MCP); restart Cursor; verify TestSprite shows connected. See [§1. Install TestSprite MCP](#1-install-testsprite-mcp-in-cursor).                                                                  |
| **API key rejected**                              | Confirm `env.API_KEY` in MCP config matches a key from [TestSprite Dashboard](https://www.testsprite.com/dashboard) → Settings → API Keys. Ensure the key is not committed to the repo.                                                          |
| **Missing testsprite\_frontend\_test\_plan.json** | Rerun the flow so the Cursor assistant calls **testsprite\_generate\_frontend\_test\_plan**; verify `testsprite_tests/` contains the file. See [§3. Run tests](#3-run-tests-with-testsprite) and [§5 Before execute](#before-execute-important). |
| **Port 8080 unreachable**                         | Ensure `npm run dev` (or `npm run build && npm run preview`) is running and the app loads at `http://localhost:8080`. See [§2. Prepare the app](#2-prepare-the-app).                                                                             |

***

**See also:** [docs/testing/index.md](/testing/index) for Vitest, Playwright, and RLS testing.