Elastic Packages support a variety of configuration variables as defined in their manifest files. Policy tests allow to check that specific sets of variables are accepted by Fleet, and they produce an expected agent policy.
Policy tests can be defined in data streams in integration packages, or at the package level in input packages.
Each test is composed of two files, one for the configuration of the policy, and another one for the expected result.
When defining the tests at the data stream level, they must be defined following this structure.
<package root>/
data_stream/
<data stream>/
_dev/
test/
policy/
test-<test name>.yml
test-<test name>.expected
When defining the tests at the package level, in input packages, they must be defined following this structure:
<package root>/
_dev/
test/
policy/
test-<test name>.yml
test-<test name>.expected
It is possible, and encouraged, to define multiple policy tests for each package or data stream.
Each package could define a configuration file in _dev/test/config.yml
to skip all the policy tests.
policy:
skip:
reason: <reason>
link: <link_to_issue>
Test configuration for the policy is defined in a YAML file prefixed with
test-
.
In these configuration files it is possible to define:
- Values for the variables of the package manifest.
- Values for the variables of the data stream manifests (only used for integration packages).
- Input to use, for packages supporting multiple input types.
For example, the following configuration tells Fleet to create a policy using an specific input, and some variables at the package level:
input: httpjson
vars:
url: http://localhost:1234/api/v1/logs
username: test
password: test
The following configuration would set a value for a variable defined at the data stream level:
data_stream:
vars:
paths:
- "/var/logs/apache/access.log*"
This configuration may look familiar to you if you are used to define system tests. The main difference is that policy tests are not going to be executed, so anything can be configured there, without expectations on having running services or reachable services. Also, no placeholders are expected to be found in policy tests.
Once you have decided the policy settings you would like to test, you should
define the expected resulting policy. In principle it is possible to define it
manually given that most of the information is included in the package, but it
can be quite cumbersome. elastic-package
is able to generate this file for
you, using the --generate
flag.
If you run the policy tests with the --generate
flag, elastic-package
will
write the found policy in the expected place.
$ elastic-package test policy --generate
Then check that the generated content is what you would expect to have.
You can run policy tests with the elastic-package test
command. If a package
includes policy tests, they will be executed if no test type is specified. You
can also run the policy tests only indicating its type:
$ elastic-package test policy
With integration packages, you can run the policy tests for a single data stream, for example:
$ elastic-package test policy --data-streams access
Results are displayed using the usual format options. When the test fail,
elastic-package
shows the differences between the expected and found policy.