// Generated by conforma CLI documentation tooling. DO NOT EDIT.
= ec test

Test your configuration files using Open Policy Agent

== Synopsis


The 'ec test' command is a thin wrapper for the 'conftest test' command. This
is an experimental feature that requires setting the EC_EXPERIMENTAL environment
variable to "1".

This command tests your configuration files using the Open Policy Agent.

The test command expects one or more input files that will be evaluated
against Open Policy Agent policies. Directories are also supported as valid
inputs.

Policies are written in the Rego language. For more
information on how to write Rego policies, see the documentation:
https://www.openpolicyagent.org/docs/latest/policy-language/

The policy location defaults to the policy directory in the local folder.
The location can be overridden with the '--policy' flag, e.g.:

	$ EC_EXPERIMENTAL=1 ec test --policy <my-directory> <input-file(s)/input-folder>

Some policies are dependant on external data. This data is loaded in separately
from policies. The location of any data directory or file can be specified with
the '--data' flag. If a directory is specified, it will be recursively searched for
any data files. Right now any '.json' or '.yaml' file will be loaded in
and made available in the Rego policies. Data will be made available in Rego based on
the file path where the data was found. For example, if data is stored
under 'policy/exceptions/my_data.yaml', and we execute the following command:

	$ EC_EXPERIMENTAL=1 ec test --data policy <input-file>

The data is available under 'import data.exceptions'.

The test command supports the '--output' flag to specify the type, e.g.:

	$ EC_EXPERIMENTAL=1 ec test -o table -p examples/kubernetes/policy examples/kubernetes/deployment.yaml

Which will return the following output:
+---------+----------------------------------+--------------------------------+
| RESULT  |               FILE               |            MESSAGE             |
+---------+----------------------------------+--------------------------------+
| success | examples/kubernetes/service.yaml |                                |
| warning | examples/kubernetes/service.yaml | Found service hello-kubernetes |
|         |                                  | but services are not allowed   |
+---------+----------------------------------+--------------------------------+

By default, it will use the regular stdout output. For a full list of available output types, see the of the '--output' flag.

The test command supports the '--update' flag to fetch the latest version of the policy at the given url.
It expects one or more urls to fetch the latest policies from, e.g.:

	$ EC_EXPERIMENTAL=1 ec test --update opa.azurecr.io/test

See the pull command for more details on supported protocols for fetching policies.

When debugging policies it can be useful to use a more verbose policy evaluation output. By using the '--trace' flag
the output will include a detailed trace of how the policy was evaluated. The trace output will be written to stderr,
while the regular output will be written to stdout. This allows you to use the '--trace' flag together with any output
format, including table, JSON, etc.

	# Trace output
	$ EC_EXPERIMENTAL=1 ec test --trace <input-file>

	# Trace output with any non-standard output format
	$ EC_EXPERIMENTAL=1 ec test --trace --output=table <input-file>

	# Redirect trace output to a file while viewing formatted output
	$ EC_EXPERIMENTAL=1 ec test --trace --output=json <input-file> 2>trace.log

[source,shell]
----
ec test <path> [path [...]] [flags]
----
== Options

--all-namespaces:: Test policies found in all namespaces (Default: false)
--capabilities:: Path to JSON file that can restrict opa functionality against a given policy. Default: all operations allowed
--combine:: Combine all config files to be evaluated together (Default: false)
-d, --data:: A list of paths from which data for the rego policies will be recursively loaded (Default: [])
--fail-on-warn:: Return a non-zero exit code if warnings or errors are found (Default: false)
-h, --help:: help for test (Default: false)
--ignore:: A regex pattern which can be used for ignoring paths
--junit-hide-message:: Do not include the violation message in the JUnit test name (Default: false)
-n, --namespace:: Test policies in a specific namespace (Default: [main])
--no-color:: Disable color when printing (Default: false)
--no-fail:: Return an exit code of zero even if a policy fails (Default: false)
-o, --output:: Output format for conftest results - valid options are: [stdout json tap table junit github azuredevops sarif] (Default: stdout)
--parser:: Parser to use to parse the configurations. Valid parsers: [cue dockerfile edn hcl1 hcl2 hocon ignore ini json jsonnet nginx properties spdx textproto toml vcl xml yaml dotenv]
-p, --policy:: Path to the Rego policy files directory (Default: [policy])
--proto-file-dirs:: A list of directories containing Protocol Buffer definitions (Default: [])
--quiet:: Disable successful test output (Default: false)
--rego-version:: Which version of Rego syntax to use. Options: v0, v1 (Default: v1)
--show-builtin-errors:: Collect and return all encountered built-in errors (Default: false)
--strict:: Enable strict mode for Rego policies (Default: false)
--suppress-exceptions:: Do not include exceptions in output (Default: false)
--tls:: Use TLS to access the registry (Default: true)
--trace:: Enable more verbose trace output for Rego queries (Default: false)
-u, --update:: A list of URLs can be provided to the update flag, which will download before the tests run (Default: [])

== Options inherited from parent commands

--debug:: same as verbose but also show function names and line numbers (Default: false)
--kubeconfig:: path to the Kubernetes config file to use
--logfile:: file to write the logging output. If not specified logging output will be written to stderr
--retry-duration:: base duration for exponential backoff calculation (Default: 1s)
--retry-factor:: exponential backoff multiplier (Default: 2)
--retry-jitter:: randomness factor for backoff calculation (0.0-1.0) (Default: 0.1)
--retry-max-retry:: maximum number of retry attempts (Default: 3)
--retry-max-wait:: maximum wait time between retries (Default: 3s)
--timeout:: max overall execution duration (Default: 5m0s)
--verbose:: more verbose output (Default: false)

== See also

 * xref:ec.adoc[ec - Conforma CLI]
