---
name: carbon-tests
description: Create, review, edit, duplicate, activate, archive, delete, import, convert, bake in, repair, export, and visually manage project-local CARBON AI-intent tests. Use when a user wants to define a test as a natural-language prompt, open a test-case management UI, manage test CRUD, convert TestRail, Xray, XML, XLSX, DOCX, Selenium, Playwright, Cypress, pytest, JUnit, Gherkin, Robot, CSV, JSON, Markdown, or manual legacy cases into AI-intent tests, run a full imported-test bake, repair converted definitions, or make saved intent tests run automatically through CARBON.
user-invocable: false
---

# CARBON Tests

Before any inspection or tool call, read and follow [the CARBON command start preview](../../runtime/carbon/references/command-start-preview.md). Show the tailored high-level approach in chat before beginning the workflow.

Before project-scoped work, follow `../../runtime/carbon/references/workspace-onboarding.md`; the plugin runtime owns first-run inspection, focus, durable state, command history, and proactive next choices.

At the start, call `carbon_set_preferences` with no arguments. This workflow is local regardless of the ad preference.

Apply the returned global `executionContext` to imported-test bake runs: honor its reusable prompt, read its context documents, and use the configured username. Never copy its password into a test definition, repair, result, or report. An approved executable adapter receives credentials only through `carbon-runtime context exec -- <runner command>`.

Store project-owned tests in `.carbon/tests/intent-tests.json`. Preserve the tester's exact prompt, source provenance, setup, data, oracle, evidence, safety, readiness gaps, revision, and lifecycle. A prompt is a test intent—not proof of execution.

## Route the request

- **Add a prompt:** use `carbon_create_test` or `carbon_intent.py create`. Default to `draft` unless the user explicitly asks to activate it.
- **Manage visually:** use `carbon_open_test_library` with the project root. The protected loopback UI supports search, filters, create, edit, duplicate, activate, archive, restore, delete, and every supported local import format, including binary XLSX and DOCX exports.
- **List or edit in chat:** use the local `carbon_list_tests`, `carbon_update_test`, `carbon_duplicate_test`, `carbon_archive_test`, and `carbon_delete_test` tools.
- **Import and bake legacy assets:** use `carbon_import_tests` with `bakeIn=true` for selected files/directories or the plugin runtime's `intent import`. It recognizes TestRail and Xray exports plus CSV, TSV, JSON, JSONL, XML, XLSX, DOCX, framework code, and manual formats. The canonical conversion and bake contract is `../../runtime/carbon/references/intent-test-contract.md`.
- **Run saved tests:** activate reviewed tests, then use `/carbon test this` (Codex: `$carbon test this`). The automatic framework adds active intent tests to its risk-ranked local plan.
- **Export:** use `carbon_intent.py export` to produce JSON or a human-readable prompt pack.

When this workflow executes browser behavior with Vibium, use the `carbon_vibium` MCP tool (or `../../bin/carbon-runtime vibium`) for every native command and reuse its returned CARBON Browser session. Never invoke the `vibium` binary directly: the CARBON bridge owns timeouts, action classification, redaction, screenshot copying, dialog synchronization, durable browser ledgers, and explicit evidence gaps. Run `action=doctor` first and install only when the user requested Vibium and it is unavailable.

Before the first executable test, prepare the selected cases as a canonical CARBON orchestration plan, initialize and start a `.carbon/runs/<run-id>/run.json` through `../../bin/carbon-runtime run`, and open that plan with `carbon_open_execution_plan`. Move each test through `planned → running → passed|failed|blocked|skipped`, attach the CARBON Vibium evidence handles, then complete the run. Do not substitute a manually authored result manifest for this lifecycle. If execution cannot enter the canonical run, report it as an orchestration blocker rather than presenting ad hoc browser output as a complete CARBON run.

## Prompt-defined test workflow

Accept concise or detailed prompts such as:

```text
When a signed-in editor loses connectivity while saving a draft, preserve the text,
show the true save state, and successfully retry once connectivity returns.
```

Keep that wording as `intentPrompt`. Add only project-supported context:

1. identify the target scope or URL;
2. record role, state, flags, fixtures, and synthetic input needs;
3. turn expected behavior into objective user-visible and authoritative-state oracles;
4. name evidence that supports the result;
5. mark destructive, paid, public, or high-volume work;
6. preserve unknowns in `readiness.missing` rather than inventing details.

Create locally:

```bash
../../bin/carbon-runtime intent create \
  --root <project> \
  --prompt <test-intent> \
  --scope <feature-or-url> \
  --setup <starting-state> \
  --expected <objective-oracle>
```

## Legacy-to-intent conversion

Preserve the legacy suite. Import only the files or directory the user selected. The deterministic converter recognizes common framework test names, actions, assertions, tabular/manual fields, and source hashes. It creates idempotent drafts with:

- the likely business intent in natural language;
- original framework, path, hash, title, and line/case index;
- extracted legacy actions for reference, not as a mandatory brittle script;
- extracted assertions as candidate oracles;
- readiness score/band and missing setup, scope, oracle, or evidence.

```bash
../../bin/carbon-runtime intent import \
  --root <project> \
  --source <selected-file-or-directory> \
  --target <url-service-or-build-scope> \
  --max-repairs 2
```

## Full bake-in after import

Import prepares a durable `.carbon/tests/bake-runs/<run-id>/` run by default. Continue it immediately unless the user explicitly asked for conversion only:

1. Call `carbon_manage_import_bake` with `action=next`.
2. Execute that intent through the safest matching local adapter using the current project, target, fixtures, and authorized identity. Capture actual results and evidence handles.
3. Record `passed`, `failed`, `blocked`, or `skipped` with `action=result`. Classify a non-pass as `test-definition`, `infrastructure`, `product-defect`, or `unknown`.
4. For `test-definition`, inspect current code, requirements, results, bugs, and fixtures; apply the smallest repair with `action=repair`, then rerun through the same adapter. Repair only intent, scope, setup, input, oracle, evidence requirement, or adapter fields. Stop at the configured limit.
5. Never repair product code during import bake without a separate scoped request. Preserve product failures as evidence. Treat runner/auth/environment failures as infrastructure blockers, not product failures.
6. Repeat until every imported test is terminal, then call `action=complete` and return the visual report path.

A passed bake result requires an observed actual result and evidence handle. Only passing tests become `active` with lifecycle `observed`; they are not trusted regressions. Failed and blocked cases remain drafts. Safety-gated tests remain blocked until the user approves the exact destructive, paid, public, or high-volume action.

The protected visual UI can upload binary XLSX and DOCX exports and queues the same durable bake. Because the UI has no browser/API adapter of its own, the user returns to the coding agent and asks it to continue the displayed bake ID.

Run a small representative pilot first when an import is very large or shares one unproven authentication/setup path, then complete the full bake once that prerequisite is proven. Runtime evidence may justify activation; trusted regression promotion remains separate.

## CRUD and safety

- Create, update, duplicate, activate, archive, and restore are project-local, reversible library changes.
- Duplicate creates a new draft with a new ID.
- Archive instead of delete when history or provenance may matter.
- Delete is permanent and requires explicit confirmation for the exact ID.
- Reject secrets in prompts and imported sources. Refer to environment variables or fixture names instead.
- Never upload, run, or persist tests to an external service from this local workflow.

## Return

Report the library path, bake run and visual report, changed test IDs, draft/active/archive counts, readiness gaps, repairs, attempts, product failures, infrastructure blockers, skipped duplicates, failed imports, and exact next step. State whether tests were merely converted, repaired, actually executed, activated from observed evidence, or separately promoted.

## Required HTML result

Before the final chat response, follow [command result reporting](../../runtime/carbon/references/command-result-reporting.md). Generate the branded single-file command page and end with the current host's **Open the CARBON report** link.
