Test and improve suites with ak:test

Use ak:test to turn a change or quality question into fresh validation evidence. The Skill can run unit, integration, end-to-end, build, coverage, and browser-based UI checks. It can also create a covering test suite, optimize a suite and its CI cost, or audit a suite for weak tests. The Skill's test-principles rules govern scope, layer, environment, and execution for every operation; load them before designing or changing tests.

Choose ak:test when validation is the outcome

Use ak:test when

• You need focused or broad test evidence after implementation or a bug repair.
• A project needs type, lint, build, or coverage validation before handoff.
• A landing page, form, or other website needs visual, responsive, accessibility, form, or console checks.
• You need a structured QA report, a new test suite, safer CI optimization, or an evidence-backed test audit.

Choose another workflow when

• A failing test needs root-cause diagnosis and a repair. Use ak:debug, then ak:fix.
• You want implementation plus its testing stage. Use ak:cook.
• You need to design the delivery plan rather than execute validation. Use ak:plan.
• You do not control the target site or lack permission for automated browsing, protected routes, form submission, or load.

Prepare the test surface

Before you start:

• Complete Onboarding, and confirm Marketing Kit is installed for the runtime and scope you are using.
• Open the project and provide the change, requirement, failing area, or test scope that should determine the commands.
• Keep the project's test runner, dependencies, fixtures, environment variables, and build tooling available.
• For UI testing, provide an authorized URL, prefer staging or fixture data, and state whether any form may submit or any account state may change.
• For protected UI routes, choose project-native test authentication or log in manually yourself. Keep credentials out of prompts, screenshots, and reports.

Select the operation

The Skill accepts [context], ui [url], or create|optimize|audit [scope]. If you provide a scope, the Skill proceeds with relevant code validation. With no arguments, it asks which operation to run. Use ui <url> to select the browser workflow directly, or start with create, optimize, or audit to work on the test suite itself.

/ak:test "Validate the signup form change: run the focused form tests and the production build."

/ak:test ui https://staging.example.com/pricing --mobile — inspect only; do not submit forms or change account state

/ak:test "Validate the signup form change: run the focused form tests and the production build."

/ak:test ui https://staging.example.com/pricing --mobile — inspect only; do not submit forms or change account state

$ak:test "Validate the signup form change: run the focused form tests and the production build."

$ak:test ui https://staging.example.com/pricing --mobile — inspect only; do not submit forms or change account state

For create, optimize, and audit, add --advice for kongming advisory checkpoints or --interview to approve each proposed change group before edits. --ultra runs five independent read-only analysis candidates in one parallel wave with one verifier: create and optimize select one winning design unchanged, while audit returns the evidence-validated, deduplicated union of findings. Failed slots are retried once; unavailable parallel read-only dispatch or fewer than five usable results after retry fails closed. The flags compose. Without --interview, create and optimize apply in-scope changes directly and report the full change list. Audit remains report-only unless suite repair is separately authorized; omitting the flag does not authorize repairs or retirement.

/ak:test create "Cover the newsletter signup workflow" --interview
/ak:test optimize "Reduce pull-request CI time" --advice
/ak:test audit "Check skipped and ineffective form tests" --ultra

Project-defined commands and coverage thresholds take priority. When the project defines no threshold, the Skill reports actual coverage and missing critical behavior instead of inventing a percentage gate. Reuse adequate existing tests; a covered refactor can add zero new tests.

Before adding tests or running broad checks, name the accepted contract and its authority, affected risk, suitable existing check, and remaining evidence gap. An inferred expectation is a hypothesis until checked against that authority. Admit a new test only for a concrete protection gap; demonstrate its intended failure when safe and practical, or report that proof as unavailable.

Combining, lowering the layer of, or retiring tests requires lifecycle review of the protected contracts, regression history, measured cost, and remaining protection. Sampled mutation-kill overlap or unchanged line coverage alone does not justify retirement. Review the remaining suite jointly, preserve required tests and mandatory gates, and obtain suite-repair authority for retirement. After authorized changes, rerun affected contracts and the same valid sampled faults against the remaining suite, followed by required gates.

Use impact selection and optional semantic modes

For a repository with a trusted test-impact manifest, optimize uses ak test optimize --base <ref> --json to plan a ranked, deterministic selection of check groups with selected and skipped reasons. Planning is read-only. --run executes the selected repository-owned commands, which is not a sandbox, and --output <new-file> keeps a local result. Uncertainty broadens selection toward the declared full suite, mandatory groups and policy checks stay required, and unresolved policy mappings block execution. This path contacts no semantic provider.

Semantic modes are opt-in only, and the Skill never infers consent from a key in the environment. With an explicit test-impact consumer grant, --semantic shadow leaves the effective baseline unchanged, and --semantic advisory can only add checks or broaden selection. Granted semantic modes can send compact facts to an external provider and incur charges. ak test classify-e2e needs its own grant and never changes E2E scheduling or the class manifest. For UI testing, a requested ak eval ui shadow experiment with an explicit ui-regression grant can add regression signals from already-observed evidence; it never turns a failure into a pass or changes the UI test result.

Optional agentic E2E through tester-army/e2e is only for projects already using it or when you explicitly request setup. This does not authorize installation, provider access, model calls, or telemetry; ordinary native UI checks need no model. Check the installed engine's capabilities before running it. Its cache replays actions, not passes: rerun exact outcome assertions on the current app. --strict-cache alone is not a no-model guarantee. If model calls are forbidden, use independently verified enforcement for the selected version or stay on the native route. Report actual replay/live execution and unfinished exploration; no findings or a cache hit does not verify unexercised release claims.

Understand what happens during a run

1. The Skill determines scope. It maps the accepted contract, authority, and risk to the smallest useful check at the lowest reliable layer, and names missing evidence before adding work.
2. The Skill runs the narrowest relevant check first. Type or build checks run when they cover the affected contract; mandatory repository gates remain.
3. The Skill executes the selected suites and analyzes the results with a focus on failures, flaky, slow, and skipped tests.
4. The Skill measures coverage when relevant and names uncovered critical paths, error handlers, and edge-case branches.
5. The Skill exercises the UI when selected. It sets a narrow charter with routes, expected behavior, account/data authority, and mandatory checks. It uses ak:agent-browser or project-native browser tests, sequentially by default; only independent, isolated targets with justified capacity warrant tester delegation. Browser checks establish browser-observable scope, not backend coverage. Assert exact identities, permissions, counts, side effects, and any specifically claimed control/path; an alternate route cannot rescue a broken control. Save relevant visual evidence in the report directory rather than taking screenshots of every page.
6. The Skill produces the report. It returns concise results for a small run or writes a structured report to the repository report location.

Keep test effects controlled

• Test commands may create coverage files, screenshots, build output, temporary data, or browser state. State allowed artifact locations, execution/retry budgets, and cleanup requirements; clean only resources owned by this run.
• Mutation proof is selective, not a routine execution or CI requirement. Use bounded fault injections only in owned disposable copies, never the active worktree. Record source identity, restore the copy exactly even on failure, verify restoration, and rerun restored behavior. Only a target assertion failure is a semantic kill; compilation, setup, infrastructure, or provider failures are invalid or inconclusive evidence, not kills.
• UI flows and end-to-end tests can submit forms or mutate data if the application behaves that way. Run them against a safe test environment.
• Real Chrome profile access requires explicit authority and necessary login state; bind to the exact profile-aware tab. External URLs, hosted browsers, and provider or operational costs need their own authority.
• The UI operation does not implement fixes. Product root-cause work belongs in ak:debug and ak:fix.

Verify the report

A complete result should give you:

• The exact scope and every command executed.
• Accepted contract and authority, source/input fingerprints before and after execution, runner/configuration, environment, and linked receipts or artifacts.
• Totals for passed, failed, and skipped tests, plus measured duration; retain every failed attempt and its raw status even when a retry passes.
• Every failed test with its error message and relevant stack trace.
• Coverage values and specific uncovered files or functions when coverage was requested.
• Build status, warnings, and dependency issues when build verification applied.
• UI pages tested, screenshot paths, console errors, and viewports checked or skipped.
• Critical issues, prioritized recommendations, and unresolved questions.
• Environment, authentication, and evidence limitations.
• Applied versus proposed suite changes, their authority, and remaining protection. Compare costs only under matched source tasks, environment, toolchain, and cache conditions: include observed setup, generation/review, runner/model calls, tokens, CI minutes, and device resources where available. Unknown metrics stay unknown; elapsed time is not billed CI minutes, and fewer tests or tokens alone do not establish savings.

Treat the run as passing only when the requested checks report zero failures, the build exits successfully when included, and project thresholds are met. A partial or skipped check proves only the surface actually executed.

A skipped or unavailable mandatory gate means insufficient evidence. Reuse receipts only when their scope, fresh source, relevant dirty/untracked inputs, configuration, and environment match; a commit SHA alone is insufficient. Invalid, stale, or foreign-scope receipts require rerunning the necessary checks, not blindly repeating the whole suite. Changed or unverified final inputs prevent a final-source pass claim; report the tested state and remaining gap.

Troubleshoot or continue

Hand failures to ak:debug and ak:fix, or continue with ak:git after the requested validation passes.

Know the current limits

• The Skill is limited to the test runners, browsers, credentials, URLs, and environments available in the current session.
• The Skill's guidance also names ak:chrome-profile and ak:web-testing. The Marketing Kit package for Claude Code does not include those Skills, so use ak:agent-browser or project-native browser tests unless they are installed from another source.
• Coverage percentages do not prove behavior outside the assertions or runtime conditions exercised.
• Cursor slash invocation is user-verified evidence, not proof of full runtime parity.