salt.modules.saltcheck¶

A module for testing the logic of states and highstates on salt minions

codeauthor:

William Cannon <william.cannon@gmail.com>

maturity:

new

Saltcheck provides unittest like functionality requiring only the knowledge of salt module execution and yaml. Saltcheck uses salt modules to return data, then runs an assertion against that return. This allows for testing with all the features included in salt modules.

In order to run state and highstate saltcheck tests, a sub-folder in the state directory must be created and named saltcheck-tests. Tests for a state should be created in files ending in *.tst and placed in the saltcheck-tests folder. tst files are run through the salt rendering system, enabling tests to be written in yaml (or renderer of choice), and include jinja, as well as the usual grain and pillar information. Like states, multiple tests can be specified in a tst file. Multiple tst files can be created in the saltcheck-tests folder, and should be named the same as the associated state. The id of a test works in the same manner as in salt state files and should be unique and descriptive.

/srv/salt/apache/
    init.sls
    config.sls
    saltcheck-tests/
        init.tst
        config.tst
        deployment_validation.tst

saltcheck_test_location: tests/integration/saltcheck

/srv/salt/apache/
    init.sls
    config.sls
    tests/integration/saltcheck/
        init.tst
        config.tst
        deployment_validation.tst

salt '*' saltcheck.run_state_tests apache,apache.config
salt '*' saltcheck.run_state_tests apache check_all=True
salt '*' saltcheck.run_highstate_tests
salt '*' saltcheck.run_state_tests apache.deployment_validation

echo_test_hello:
  module_and_function: test.echo
  args:
    - "hello"
  kwargs:
  assertion: assertEqual
  expected_return:  'hello'

{% for package in ["apache2", "openssh"] %}
{# or another example #}
{# for package in salt['pillar.get']("packages") #}
test_{{ package }}_latest:
  module_and_function: pkg.upgrade_available
  args:
    - {{ package }}
  assertion: assertFalse
{% endfor %}

setup_test_environment:
  module_and_function: saltcheck.state_apply
  args:
    - common
  pillar_data:
    data: value

verify_vim:
  module_and_function: pkg.version
  args:
    - vim
  assertion: assertNotEmpty

{% for package in ["apache2", "openssh"] %}
{# or another example #}
{# for package in salt['pillar.get']("packages") #}
test_{{ package }}_latest:
  module_and_function: pkg.upgrade_available
  args:
    - {{ package }}
  assertion: assertFalse
{% endfor %}

setup_test_environment:
  module_and_function: saltcheck.state_apply
  args:
    - common
  pillar-data:
    data: value

verify_vim:
  module_and_function: pkg.version
  args:
    - vim
  assertion: assertNotEmpty

package_latest:
  module_and_function: pkg.upgrade_available
  args:
    - apache2
  assertion: assertFalse
  skip: True

validate_shell:
  module_and_function: user.info
  args:
    - root
  assertion: assertEqual
  expected_return: /bin/bash
  assertion_section: shell

validate_smb_signing:
  module_and_function: lgpo.get
  args:
    - 'Machine'
  kwargs:
    return_full_policy_names: True
  assertion: assertEqual
  expected_return: Enabled
  assertion_section: 'Computer Configuration|Microsoft network client: Digitally sign communications (always)'
  assertion_section_delimiter: '|'

validate_env_nameNode:
  module_and_function: hadoop.dfs
  args:
    - text
    - /oozie/common/env.properties
  expected_return: nameNode = hdfs://nameservice2
  assertion: assertNotIn
  print_result: False

multiple_validations:
  module_and_function: network.netstat
  assertions:
    - assertion: assertEqual
      assertion_section: "0:program"
      expected_return: "systemd-resolve"
    - assertion: assertEqual
      assertion_section: "0:proto"
      expected_return: "udp"
  output_details: True

class salt.modules.saltcheck.SaltCheck(saltenv='base')¶

This class validates and runs the saltchecks

run_test(test_dict)¶

Run a single saltcheck test

class salt.modules.saltcheck.StateTestLoader(saltenv='base')¶

Class loads in test files for a state e.g. state_dir/saltcheck-tests/[1.tst, 2.tst, 3.tst]

add_test_files_for_sls(sls_name, check_all=False)¶

Detects states used, caches needed files, and adds to test list

load_test_suite()¶

Load tests either from one file, or a set of files

salt.modules.saltcheck.parallel_scheck(data)¶

triggers salt-call in parallel

salt.modules.saltcheck.report_highstate_tests(saltenv=None)¶

Report on tests for states assigned to the minion through highstate. Quits with the exit code for the number of missing tests.

CLI Example:

salt '*' saltcheck.report_highstate_tests

New in version 3000.

salt.modules.saltcheck.run_highstate_tests(saltenv=None, only_fails=False)¶

Execute all tests for states assigned to the minion through highstate and return results

Parameters:

• saltenv (str) -- optional saltenv. Defaults to base

• only_fails (bool) -- boolean to only print failure results

CLI Example:

salt '*' saltcheck.run_highstate_tests

salt.modules.saltcheck.run_state_tests(state, saltenv=None, check_all=False, only_fails=False)¶

Execute tests for a salt state and return results Nested states will also be tested

Parameters:

• state (str) -- state name for which to run associated .tst test files

• saltenv (str) -- optional saltenv. Defaults to base

• check_all (bool) -- boolean to run all tests in state/saltcheck-tests directory

• only_fails (bool) -- boolean to only print failure results

CLI Example:

salt '*' saltcheck.run_state_tests postfix,common

Tests will be run in parallel by adding "saltcheck_parallel: True" in minion config. When enabled, saltcheck will use up to the number of cores detected. This can be limited by setting the "saltcheck_processes" value to an integer to set the maximum number of parallel processes.

salt.modules.saltcheck.run_state_tests_ssh(state, saltenv=None, check_all=False, only_fails=False)¶

This function is an alias of run_state_tests.

Execute tests for a salt state and return results Nested states will also be tested

param str state:

state name for which to run associated .tst test files

param str saltenv:

optional saltenv. Defaults to base

param bool check_all:

boolean to run all tests in state/saltcheck-tests directory

param bool only_fails:

boolean to only print failure results

CLI Example:

salt '*' saltcheck.run_state_tests postfix,common

Tests will be run in parallel by adding "saltcheck_parallel: True" in minion config. When enabled, saltcheck will use up to the number of cores detected. This can be limited by setting the "saltcheck_processes" value to an integer to set the maximum number of parallel processes.

salt.modules.saltcheck.run_test(**kwargs)¶

Execute one saltcheck test and return result

Parameters:

test (keyword arg) --

CLI Example:

salt '*' saltcheck.run_test
    test='{"module_and_function": "test.echo",
           "assertion": "assertEqual",
           "expected_return": "This works!",
           "args":["This works!"] }'

salt.modules.saltcheck.state_apply(state_name, **kwargs)¶

Runs state.apply with given options to set up test data. Intended to be used for optional test setup or teardown

Reference the state.apply module documentation for arguments and usage options

CLI Example:

salt '*' saltcheck.state_apply postfix