testsprite-onboard

name

testsprite-onboard

description

Stand up a complete, runnable TestSprite test suite for the current repo at first use — create a project (with a target URL and auth), derive a coherent set of tests from the codebase, batch-create them, and smoke-run a few to a green verdict so the user immediately has something worth running. Use ONLY when a repo has no TestSprite tests yet (a fresh project), right after `testsprite setup`, or when the user asks to "set up / bootstrap / seed tests". This is first-run setup, NOT change verification — once a project already has tests, use the testsprite-verify skill instead.

TestSprite: onboard a repo with a seed test suite

Your job is to take a repo that has no TestSprite tests yet and leave it with a coherent, runnable suite plus a couple of already-green smoke tests — in one pass. A new user who can immediately run a real, passing test is an activated user; an empty project is the #1 drop-off.

This skill only uses shipped CLI commands. It works the same whether the user is on the V2 or V3 backend — the CLI routes internally. Do not call backend APIs directly.

When to use

• Right after testsprite setup, or any time the active project has 0–1 tests.
• The user says "set up tests", "bootstrap", "seed a suite", "get me started", or similar.

When NOT to use

• The project already has tests — that's the testsprite-verify skill's job, not this one.
• The user only changed code and wants it checked — again, testsprite-verify.

Prerequisites

testsprite setup has run (an API key is configured). If testsprite project list errors on auth, stop and tell the user to run testsprite setup first — don't try to configure for them.

Steps

1. Understand the app (don't skip — this is where coverage quality comes from)

Read the repo to establish, concretely:

• Frontend: the deployed/local URL, the 4–8 most important user flows (auth, core CRUD, checkout, search, settings…), and whether flows need login.
• Backend: the key API endpoints and their success/error contracts.

Prefer code-derived routes/handlers over guessing — you have the source; use it. This beats a blind crawl.

2. Create the project (FE must have a URL)

Frontend:

testsprite project create --type frontend --name "<repo name>" --url <app-url> \
  [--username <user> --password-file <path-to-secret>]

Backend:

testsprite project create --type backend --name "<repo name>"

Capture the returned projectId.

Critical for FE: a frontend test with no resolvable target URL fails immediately with No environment URL configured — the suite goes all-red. Always pass --url. If flows need login, pass --username/--password-file now so authenticated pages are reachable.

3. Author the tests (quality over quantity)

Frontend — one JSON plan file per flow, in a directory (e.g. ./testsprite-plans/). Each file is a COMPLETE plan and must include projectId (from step 2), type: "frontend", name, and planSteps — create-batch reads the project from each file, not from a flag:

{
  "projectId": "<projectId from step 2>",
  "type": "frontend",
  "name": "Checkout — guest can complete a purchase",
  "planSteps": [
    { "type": "action", "description": "Navigate to /products and open the first product" },
    { "type": "action", "description": "Click 'Add to cart', then go to /cart" },
    {
      "type": "assertion",
      "description": "The cart shows exactly 1 line item with the product's name and price"
    },
    { "type": "action", "description": "Proceed to checkout as guest and submit the test payment" },
    { "type": "assertion", "description": "A confirmation page appears showing an order number" }
  ]
}

Backend — one .py file per endpoint, using requests with concrete assertions on status code and response body.

Assertion rule (this is the whole game for FE): every assertion step must name a concrete, observable outcome — an element, text, URL, count, or status. Never write "verify it works", "check the page loads", or other narrative that an AI judge can rubber-stamp. Vague assertions are how false-PASS sneaks in.

Aim for ~8–15 tests covering the core flows. Don't pad.

4. Batch-create

Frontend (one call, up to 50 plans from the directory — create-batch is FE-only and has no --project flag; the project comes from each plan file's projectId):

testsprite test create-batch --plan-from-dir ./testsprite-plans

Backend (one call per file — create-batch is FE-only; --name is required):

testsprite test create --type backend --name "<behavior being tested>" \
  --code-file ./tests/<endpoint>.py --project <projectId>

Capture the created testIds from the output.

5. Smoke-run a few — NOT all (protect credits)

Pick the 2–3 highest-value happy-path tests (prefer ones you're most confident are green) and run only those:

testsprite test run <testId> --wait

Do not run the whole suite automatically — a 20-test FE suite is ~40 credits and a free account only has 150. Running the full suite is the user's explicit choice.

6. Report

Tell the user, plainly:

• "Your project now has N tests covering: ."
• "I smoke-ran M — here's the result: <pass/fail + the dashboard link from the run output>."
• "To run the rest (≈X credits — state the cost so they choose knowingly):
  • frontend — run each remaining test by id: testsprite test run <testId> --wait (there is no --all for frontend);
  • backend — testsprite test run --all --project <id> (wave-ordered, runs every BE test)."

Quality checklist (self-check before reporting done)

• FE project has a real --url; login configured if the app needs it.
• Every FE assertion names a concrete, observable outcome (no "verify it works").
• Tests cover the core flows you found in the code, not just one page.
• Smoke-ran 2–3 happy-path tests, not the whole suite.
• Reported test count, smoke result + dashboard link, and the cost to run the rest.

Don'ts

• Don't auto-run the full suite (credit wall / surprise 402).
• Don't write narrative assertions an AI judge can't fail.
• Don't call backend endpoints directly — only the testsprite CLI.
• Don't create a FE project without a URL.
• Don't re-seed a project that already has tests — that's not this skill's job.

Hand off to verify

This skill's job ends once the project has a seeded suite and a first green run. From here on, the testsprite-verify skill takes over: after the user changes code, it runs the tests covering that change before they report the work done. Onboard once; verify continuously.