Skip to content

policy_testing.md

Latest commit

 

History

History
155 lines (123 loc) · 5.57 KB

policy_testing.md

File metadata and controls

155 lines (123 loc) · 5.57 KB
Raw

HOWTO: Writing policy tests for a package

Introduction

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.

Defining policy tests

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.

Global test configuration

Each package can define a configuration file in _dev/test/config.yml to control how policy tests are run. The full shape of the policy block is:

policy:
  skip:
    reason: <reason>
    link: <link_to_issue>
  requires:
    - source: "../path/to/input_pkg"   # local directory or .zip (relative to package root)
    - package: sql_input               # registry-based; requires version
      version: "0.2.0"
  ignore_fields:
    - state.user_agent                 # strip this field from comparison

The skip key skips all policy tests with a mandatory reason and optional issue link.

The requires key is used for integration packages with requires that declare requires.input in their manifest.yml. It tells the policy test runner which local source path (or registry version) to use for each required input package when bundling the integration before running the tests. Without this, the runner fetches dependencies from the configured package registry.

  • Use source when the input package is not yet published to the registry (local development).
  • Use package + version to pin a specific registry version.
  • source and package/version are mutually exclusive in the same entry.

The ignore_fields key lists stream-level field paths to strip from both sides before comparing the actual policy against the expected file. Paths use dot notation scoped to the stream level. For example, state.user_agent removes inputs[].streams[].state.user_agent from comparison. This is useful when a rendered field contains a dynamic value (such as the package version embedded in a User-Agent header) that changes across versions but does not need to be asserted exactly.

For full details on integrations with requires and source overrides, see HOWTO: Enable dependency management.

Defining the configuration of the policy

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.
  • Overrides for the data stream routing (only used for input packages). See Overriding data stream type and dataset for input packages in the system testing documentation.

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.

Defining the expected policy

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.

Running policy tests

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.