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 and repair 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 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 production-risk and maintainability findings from a diff. Use ak:code-review.
• You want implementation plus its default testing and review stages. Use ak:cook.
• You need to design the delivery plan rather than execute validation. Use ak:plan.

Prepare the test surface

Before you start:

• Complete Onboarding, and confirm Engineer 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 the URL and start the required application yourself or explicitly authorize the workflow that starts it.
• For protected UI routes, choose project-native test authentication or approve use of the real Chrome profile and complete any required manual login.

Select the operation

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. Any suite change, optimize or audit proposal, or QA report must stay consistent with the test-principles rules.

/ak:test "Validate the session expiry change: run typecheck, the focused session tests, affected integration tests, and coverage for the changed module."

/ak:test ui http://localhost:3000/settings

/ak:test "Validate the session expiry change: run typecheck, the focused session tests, affected integration tests, and coverage for the changed module."

/ak:test ui http://localhost:3000/settings

$ak:test "Validate the session expiry change: run typecheck, the focused session tests, affected integration tests, and coverage for the changed module."

$ak:test ui http://localhost:3000/settings

For create, optimize, and audit, add --advice for kongming advisory checkpoints or --interview to approve each proposed change group before edits. --ultra runs five read-only analysis candidates: create and optimize select one winning design unchanged, while audit returns the evidence-validated, deduplicated union of findings. Five initial candidate slots are dispatched in one parallel wave; failed slots are retried once. If parallel read-only dispatch is unavailable or fewer than five results are usable after the retry, the run fails closed. Without --interview, the Skill applies supported changes directly and still reports the full change list.

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

Project-defined commands and thresholds take priority. When the project does not define a coverage threshold, the Skill reports actual coverage and the critical behaviors still missing tests; it does not invent a percentage gate. When create builds a new suite, it aims for the project's threshold, with 80% on critical paths as the default.

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

The default and ui operations follow this validation flow:

1. The Skill determines scope. It connects recent changes or requirements to the smallest useful validation surface using risk-based scope and the lowest reliable layer, and identifies critical paths and error scenarios.
2. The Skill runs pre-flight checks. Type, syntax, lint, or language-specific analysis runs before behavioral tests so compilation failures are visible early.
3. The Skill executes the selected suites. It starts focused, expands to integration or end-to-end coverage when the blast radius requires it, and preserves skipped, flaky, slow, and failed tests.
4. The Skill measures coverage when relevant. It reports line, branch, and function coverage, then identifies uncovered files, error handlers, and edge-case branches instead of relying on one percentage.
5. The Skill verifies the build. It runs the project-appropriate production build when build compatibility belongs to the requested scope.
6. The Skill exercises the UI when selected. It chooses an isolated browser, a profile-aware Chrome path, or project-native browser tests; captures screenshots; and checks interactions, responsiveness, accessibility, and console output.
7. The Skill produces the report. It organizes results, failures, coverage, build status, critical issues, recommendations, and unresolved questions in the configured 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 may modify product code briefly to prove a test fails against a plausible bug. The workflow must revert every such mutation after observing the result; an unreverted mutation is a blocker.
• Run suites against a safe test environment. UI flows and end-to-end tests can submit forms or mutate data if the application behaves that way.
• Real Chrome profile testing can access the user's authenticated session. Use it only when that state is required and bind to the exact profile-aware tab.
• External URLs, hosted browsers, performance services, or production-like environments can incur provider or operational cost and need separate authority.
• The default and ui operations report product defects without implementing fixes. audit may repair the test suite and CI evidence, but product root-cause work still belongs in ak:debug and ak:fix.

Verify the report

A complete default or ui result should give you:

• The exact scope and every command executed.
• Totals for passed, failed, and skipped tests, plus duration.
• Complete failed-test names, essential error output, and relevant stack traces.
• Coverage values and concrete gaps when coverage was requested.
• Build status, warnings, and dependency issues when build verification applied.
• UI pages and flows tested, screenshot paths, console findings, viewports, and any skipped browser checks.
• Critical issues and prioritized recommendations.
• Environment, authentication, or evidence limitations listed explicitly.

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:code-review 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.
• Coverage percentages do not prove behavior outside the assertions or runtime conditions exercised.
• Visual screenshots do not replace interaction, accessibility, console, or repeatable project-native tests.
• Cursor slash invocation is user-verified evidence, not proof of full runtime parity.
• Available operations depend on the installed Engineer Kit release.