# Create, edit, and share tests

Every test stores a complete typed definition and points to a current immutable revision. Editing creates another revision; it does not rewrite the definition used by an earlier invocation. This is the foundation for comparing a past result with the exact test that produced it.

## Create and edit

Choose Simulation, Next Reply, or Tool Invocation, give the test a clear behavioral name, and complete the required fields for that type. Common fields include conversation history, scalar dynamic variables, optional folder, and conversation source metadata. Definitions are validated as a whole, so unknown fields and incomplete type-specific settings are rejected.

An update must include `current_revision_id`. If another editor saved first, the request fails with `conflict_test_revision` instead of overwriting their work. Reload the test, compare the new revision, reapply the intended change, and save again. **Save as new** creates an independent test and revision history.

## Share within the workspace

The creator, workspace admins, and owners can manage access. A **Viewer** can read and run a shared test. An **Editor** can revise its contents, but cannot move it or manage sharing as though they owned it. Access can be granted only to an existing member of the same workspace.

Sharing does not create a public link and does not cross the workspace boundary. Removing a membership also removes effective access. Private or cross-workspace resources return `not_found` where revealing their existence would leak data.

## Preserve review evidence

Deleting a test is a soft delete and requires a dashboard session. The operation removes attachments from mutable Agent drafts, while immutable revisions and past results remain available through their invocation evidence. API keys can perform non-destructive library operations, but cannot share or delete tests.

Treat an allowed workspace API key as a privileged automation credential. On Agent Testing routes that accept it, Operade authorizes the key at workspace-admin scope: it can list and read private tests created by other members, edit or move those tests, and list or read invocations created by other members. Viewer and Editor sharing filters apply to signed-in members, not to an allowed API key. The key still cannot cross its Workspace or call dashboard-only sharing and delete routes.

Use [Test library and folders](/docs/agent-testing/library-and-folders) for organization and [Troubleshooting](/docs/agent-testing/troubleshooting) for stale revision recovery. See [Create an agent test](/docs/api-reference/agent-tests/create-agent-test) for the HTTP contract.