circleci-smarter-testing

name	circleci-smarter-testing
description	Onboard onto CircleCI Smarter Testing (testsuite) with `.circleci/test-suites.yml`, config wiring, `circleci run testsuite`, and `--doctor` until checks pass. Use for Smarter Testing, testsuite, test-suites YAML, test impact analysis, dynamic test splitting, auto rerun failed tests, or migrating raw test commands.

CircleCI Smarter Testing

Overview

Beta (Discuss). Create or adjust .circleci/test-suites.yml, wire it into CI, and validate with --doctor until checks pass. Let doctor diagnose YAML, command, JUnit, and testsuite errors before adding extra guidance.

Doctor command (required)

When iterating with --doctor, the agent must always run this exact command (substitute the suite name only):

$ circleci run testsuite "<suite name>" --doctor --json

Example output:

{
  "checks": [
	{
	  "name": "< check name >",
	  "state": "< success | skipped | failed >"
	}
  ],
  "action_items": [
	{
	  "title": "< what happened >",
	  "content": "< advice on how to fix the problem >"
	}
  ],
  "next_steps": [
	{
	  "title": "< next step >",
	  "content": "< suggestion for the next thing to configure >"
    }
  ]
}

Do not modify this command: no pipes, tail, redirects, backgrounding, or truncation.

Scope: testsuite setup and validation. Primary doc: Getting started.

Lazy references: read only what the task needs—do not load every reference file up front.

• CI / store_test_results → references/ci-and-junit.md

Inputs To Gather

• Runner, test root, existing .circleci/config.yml
• Hand off: circleci-cli (install/auth/plugin) | circleci-config (JUnit/test results) | circleci-builds (CI fails after doctor-clean config)

Workflow

1. Local vs CI — Local needs CLI + testsuite plugin (brew install circleci/tap/circleci-testsuite on macOS; binaries on Linux/WSL). CI uses circleci run testsuite on executors + ci-and-junit.md.
2. Inspect — runner, layout, existing CI; reuse documented test commands; run testsuite from the test root (no cd in YAML).
3. Doctor — run the exact doctor command above; apply its advice; repeat until pass.
4. Next steps — Ask to configure next steps from the doctor command output. Run the doctor command after each.

Guardrails

• Never skip doctor after editing test-suites.yml.
• No secrets in YAML—use contexts/env vars; document variable names only.
• Do not swap a working testsuite for legacy circleci tests split / circleci tests run.

Reference map

• ci-and-junit.md — full config.yml, JUnit directory upload.

Output Contract

Provide:

1. Runner, working directory, files changed, commands run (--doctor and follow-ups).
2. What to commit and open items (beta access, blocked prerequisites).