# salt.states.test

## Test States

Provide test case states that enable easy testing of things to do with state calls, e.g. running, calling, logging, output filtering etc.

    always-passes-with-any-kwarg:
      test.nop:
        - name: foo
        - something: else
        - foo: bar

    always-passes:
      test.succeed_without_changes:
        - name: foo

    always-fails:
      test.fail_without_changes:
        - name: foo

    always-changes-and-succeeds:
      test.succeed_with_changes:
        - name: foo

    always-changes-and-fails:
      test.fail_with_changes:
        - name: foo

    my-custom-combo:
      test.configurable_test_state:
        - name: foo
        - changes: True
        - result: False
        - comment: bar.baz
        - warnings: A warning

    is-pillar-foo-present-and-bar-is-int:
      test.check_pillar:
        - present:
            - foo
        - integer:
            - bar

You may also use these states for controlled failure in state definitions, for example if certain conditions in pillar or grains do not apply. The following state definition will fail with a message "OS not supported!" when grains['os'] is neither Ubuntu nor CentOS:

    {% if grains['os'] in ['Ubuntu', 'CentOS'] %}

    # Your state definitions go here

    {% else %}
    failure:
      test.fail_without_changes:
        - name: "OS not supported!"
        - failhard: True
    {% endif %}

salt.states.test.check_pillar(name, present=None, boolean=None, integer=None, string=None, listing=None, dictionary=None, verbose=False)

  Checks the presence and, optionally, the type of given keys in Pillar

  Supported kwargs for types are: - boolean (bool) - integer (int) - string (str) - listing (list) - dictionary (dict)

  Checking for None type pillars is not implemented yet.

      is-pillar-foo-present-and-bar-is-int:
        test.check_pillar:
          - present:
              - foo
          - integer:
              - bar

salt.states.test.configurable_test_state(name, changes=True, result=True, comment='', warnings=None, allow_test_mode_failure=False)

  Added in version 2014.7.0.

  A configurable test state which allows for more control over the return data

  name

    A unique string to serve as the state's ID

  changesTrue

    Controls whether or not the state reports that there were changes. There are three supported values for this argument:

    - If `True`, the state will report changes

    - If `False`, the state will report no changes

    - If `"Random"`, the state will randomly report either changes or no changes.

  resultTrue

    Controls the result for for the state. Like `changes`, there are three supported values for this argument:

    - If `True`, the state will report a `True` result

    - If `False`, the state will report a `False` result

    - If `"Random"`, the state will randomly report either `True`

    Note

    The result will be reported as `None` if all of the following are true:

    1. The state is being run in test mode (i.e. `test=True` on the CLI)

    2. `result` is `True` (either explicitly, or via being set to `"Random"`)

    3. `changes` is `True` (either explicitly, or via being set to `"Random"`)

  comment""

    Comment field field for the state. By default, this is an empty string.

  warnings

    A string (or a list of strings) to fill the warnings field with. Default is None

    Added in version 3000.

  allow_test_mode_failure

    When False, running this state in test mode can only return a True or None result. When set to True and result is set to False, the test mode result will be False. Default is False

    Added in version 3007.0.

salt.states.test.fail_with_changes(name, **kwargs)

  Added in version 2014.7.0.

  Returns `False` with an non-empty `changes` dictionary. Useful for testing requisites.

  name

    A unique string to serve as the state's ID

salt.states.test.fail_without_changes(name, **kwargs)

  Added in version 2014.7.0.

  Returns failure

  name

    A unique string to serve as the state's ID

salt.states.test.mod_watch(name, sfun=None, **kwargs)

  Call this function via a watch statement

  Added in version 2014.7.0.

  Any parameters in the state return dictionary can be customized by adding the keywords `result`, `comment`, and `changes`.

      this_state_will_return_changes:
        test.succeed_with_changes

      this_state_will_NOT_return_changes:
        test.succeed_without_changes

      this_state_is_watching_another_state:
        test.succeed_without_changes:
          - comment: 'This is a custom comment'
          - watch:
            - test: this_state_will_return_changes
            - test: this_state_will_NOT_return_changes

      this_state_is_also_watching_another_state:
        test.succeed_without_changes:
          - watch:
            - test: this_state_will_NOT_return_changes

salt.states.test.nop(name, **kwargs)

  Added in version 2015.8.1.

  A no-op state that does nothing. Useful in conjunction with the `use` requisite, or in templates which could otherwise be empty due to jinja rendering.

  name

    A unique string to serve as the state's ID

salt.states.test.show_notification(name, text=None, **kwargs)

  Added in version 2015.8.0.

  Simple notification using text argument.

  name

    A unique string to serve as the state's ID

  text

    Text to return in the comment field

salt.states.test.succeed_with_changes(name, **kwargs)

  Added in version 2014.7.0.

  Returns `True` with an non-empty `changes` dictionary. Useful for testing requisites.

  name

    A unique string to serve as the state's ID

salt.states.test.succeed_without_changes(name, **kwargs)

  Added in version 2014.7.0.

  Returns successful

  name

    A unique string to serve as the state's ID