# atmos plugin test

Test a prebuilt plugin using explicit fixtures and the shared Atmos test runner.

> ⚠️ Experimental

## Usage

```shell
atmos plugin test [directory]
```

Unlike [`plugin validate`](validate.mdx), `test` **starts the plugin executable**: it launches the
prebuilt binary and calls its handlers against local fixtures, so run [`plugin build`](build.mdx)
first. The manifest-to-handler agreement check always runs. Local suites then run registered
extension checks and the selected fixtures from `plugin.tests.yaml`. Extension checks
use names such as `extension/command/about` and support `--run` filtering. Live integration steps
run only with `--integration`, and an empty live suite is an error.

By default, each completed check gets a readable description and a success or failure
indicator, followed by the total results. The OIDC check describes the simulated
login, token validation, credential exchange, cache, refresh, and logout flow.
Progress uses stderr. Select `--format json` to write the structured report to stdout;
the stable names such as `manifest-handler-agreement`, `oidc-lifecycle`, and
`command/about` remain available for automation and `--run`.

### Failures

A failed check prints its evidence directly under the failure line, so you do not need to rerun
the suite in another format. For a command fixture, the detail names each field that differs
(`stdout`, `stderr`, or `exit_code`), the byte offset of the first difference, and the expected
and actual values. Values are masked for secrets and truncated to 2 KiB each. The same text is
the `detail` field of the failed result in `--format json`. Plugin error messages are not
echoed, because they can contain credentials; the report carries only the masked, bounded detail.

`--run` selects tests whose names contain the given text. When it matches nothing, `test` fails
with an error that lists the available test names, rather than passing with zero checks.

### Policy

`test` runs a developer's local, unsigned plugin, so it is governed only by `on: plugin` policy
rules for the `test` operation. Such a rule sees `input.operation == 'test'`, `input.origin == 'development'`,
and `input.path` holding the tested directory. It is deliberately not subject to
`plugins.policy.require_signature`: an author must be able to test a plugin before there is
anything to sign. That setting governs released packages when they are installed or activated.
To let development plugins be tested but not run, deny `input.origin == 'development' && input.operation != 'test'`.
See [plugin policies](/policies/plugins) and the
[plugin development tutorial](/tutorials/plugin-development#govern-local-builds-with-policy).

## Arguments and flags

- **directory**
  Package directory containing plugin.yaml, plugin.tests.yaml, and its compiled executable.
- **--run**
  Select test names containing this text. Fails with the list of available tests when nothing matches.
- **--format**
  Report format: text (default) or json.
- **--integration**
  Run explicitly configured live integration steps instead of local mock fixtures.

## Examples

```shell
atmos plugin test ./corporate-oidc
atmos plugin test ./corporate-oidc --run=oidc-lifecycle --format=json
atmos plugin test ./corporate-oidc --integration
```