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. The flags compose. Without --interview, create and optimize apply changes directly and report the full change list; audit reports findings and repairs only when you also request fixes.

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

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.

Understand what happens during a run

1. The Skill determines scope. It connects recent changes or requirements to the smallest useful validation surface at the lowest reliable layer.
2. The Skill runs the narrowest relevant check first. Type or build checks run when they cover the affected contract.
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 uses ak:agent-browser or project-native browser tests, organizes the test plan, saves screenshots in one report directory, and can split pages, forms, navigation, user flows, accessibility, responsive layout, performance, security, and SEO checks across parallel tester subagents.
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 the allowed artifact locations and cleanup requirements.
• Mutation spot-checks for create or audit modify the code under test once to prove a test fails on a plausible bug, then revert it.
• 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.
• 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.
• Totals for passed, failed, and skipped tests, plus duration.
• 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.

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.

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.