atmos plugin test
Usage
atmos plugin test [directory]
Unlike plugin validate, test starts the plugin executable: it launches the
prebuilt binary and calls its handlers against local fixtures, so run plugin build
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 and the
plugin development tutorial.
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
atmos plugin test ./corporate-oidc
atmos plugin test ./corporate-oidc --run=oidc-lifecycle --format=json
atmos plugin test ./corporate-oidc --integration
