# Circleci Testsuite

> Onboard a project onto CircleCI's testsuite (`.circleci/test-suites.yml` + `circleci testsuite run`), or migrate off legacy `circleci tests split`/raw test commands onto it. Initial setup for smarter testing features. Driven entirely by `circleci testsuite doctor`. Use for testsuite, test-suites YAML, discover/run commands, JUnit wiring, or migrating an existing test step. For test impact analysis, dynamic test splitting, or auto-rerun, use the circleci-smarter-testing skill instead once testsuite is set up.

- Skill: `circleci-public/circleci-testsuite` (Agent Skill)
- Install (CLI): `npx skillmds@latest add circleci-public/circleci-testsuite`
- Raw SKILL.md: https://api.skillmd.com/api/skills/circleci-public/circleci-testsuite/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: circleci-public (https://skillmd.com/u/circleci-public)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/circleci-public/circleci-testsuite

---


# CircleCI Testsuite

Testsuite replaces a raw test command with `.circleci/test-suites.yml` + `circleci testsuite run "<suite name>"`. This skill only gets a suite onboarded and doctor-clean — it does not enable Smarter Testing's paid features (test impact analysis, dynamic test splitting). Hand those to `circleci-smarter-testing` once this finishes.

Always start with:

```shell
circleci testsuite doctor "<suite name>" --json
```

Doctor's `action_items` say exactly what's wrong and how to fix it. Apply the fix, rerun doctor, repeat until `checks` all pass. Never run the project's raw test command or the YAML's `discover`/`run` directly to validate — always go through doctor.

- **No config found** — use doctor's starter `test-suites.yml`, adapted to the project's real test runner. If a test step already exists (raw `npm test`/`pytest`/`go test`, or legacy `circleci tests split`/`circleci tests run`), base `discover`/`run` on it rather than inventing a new one.
- **JUnit atoms not matching results** — usually the reporter isn't emitting a `file` attribute per test case. Fix at the source, e.g. `JEST_JUNIT_ADD_FILE_ATTRIBUTE=true` for jest-junit, or `--override-ini=junit_family=xunit1` for pytest.
- Ignore any `next_steps` about test impact analysis, dynamic test splitting, auto-rerun, or `store-test-results` — paid features, out of scope here, owned by `circleci-smarter-testing`.

Once doctor is clean: replace the old test step in `.circleci/config.yml` with `circleci testsuite run "<suite name>"`, and remove now-redundant legacy test-split steps. Leave any existing `store_test_results` job step as-is — `circleci-smarter-testing` replaces it later with `options: store-test-results: true`. Tell the user testsuite is onboarded and that `circleci-smarter-testing` can add test impact analysis, dynamic test splitting, or auto-rerun on top.

## Guardrails

- Do not add any `options:` (`store-test-results`, `test-impact-analysis`, `dynamic-test-splitting`, `max-auto-rerun`) — all Smarter Testing features, paid and free, are out of scope for this skill.
- No secrets in `test-suites.yml` — use contexts/env vars.
- Hand off CLI install/auth issues to `circleci-cli`, other config/caching/workspace work to `circleci-config`, and CI failures after a doctor-clean config to `circleci-builds`.

## Output Contract

Remove extraneous files created during setup. Report the runner, files changed, the final doctor output, and any blocked prerequisites.