ansible-tap

AnsibleのためのTest Anything Protocol (TAP)プロデューサーです。

このコールバックプラグインを使用すると、AnsibleのプレイブックとしてTAPテストスイートを書くことができます。これは、ServerspecやTestinfraのAnsible専用の代替品と考えてください。

必要条件

• Ansible 2
• Python 2.7以上

インストール

このプラグインを直接ansible-galaxyを使ってインストールすることはできませんが、ansible-galaxyを使ってダウンロードできます：

ansible-galaxy install -p roles/ benwebber.tap

ロールディレクトリに移動してmake installを実行します：

cd roles/benwebber.tap
make install

これにより、プラグインが ~/.ansible/plugins/callback にコピーされます。

使い方

Ansibleがこのプラグインを標準出力コールバックとして使用するように設定します：

ANSIBLE_STDOUT_CALLBACK=tap ansible-playbook -i hosts test.yml -l hostname

ansible.cfgにもデフォルトのコールバックとして設定できます：

[defaults]
stdout_callback=tap

Ansibleテストの作成

デフォルトでは、Ansibleはタスクが失敗した場合、プレイブックを中止します。すべてのテストにignore_errors: trueを設定すると、この動作を無効にできます：

- name: サービスが起動しているかチェック
  command: systemctl is-active service
  register: is_active
  tags: diagnostic

- name: サービスが起動していることを確認
  assert:
    that: is_active.rc == 0
  ignore_errors: true

これにより、Ansibleは予期しない失敗を除けば、テストスイート全体を実行します。

多数のテストがある場合、blockにignore_errors: trueを設定できます：

- name: サービスが起動しているかチェック
  command: systemctl is-active service
  register: is_active
  tags: diagnostic

- name: サービスが有効になっているかチェック
  command: systemctl is-enabled service
  register: is_enabled
  tags: diagnostic

- ignore_errors: true
  block:
  - name: サービスが起動していることを確認
    assert:
      that: is_active.rc == 0

  - name: サービスが有効になっていることを確認
    assert:
      that: is_enabled.rc == 0

タスクが失敗した場合、プラグインはトラブルシューティング情報を埋め込んだYAML文書として出力します：

not ok - assert: 変数が設定されていることを確認
  ---
  _ansible_no_log: false
  _ansible_verbose_always: true
  assertion: statusが定義されている
  changed: false
  evaluated_to: false
  failed: true
  invocation:
    module_args:
      that: statusが定義されている
    module_name: assert
  ...

TAPストリームからタスクを除外

多くの場合、テストの結果は前のタスクに依存します。これらのセットアップタスクをTAPストリームから除外したいでしょう。

そのためには、セットアップタスクにdiagnosticタグを付けるだけです：

- name: 次のテストをセットアップ
  command: 'true'
  register: true_
  tags: diagnostic

- name: 常にパスすることを確認
  assert:
    that: true_.rc == 0
  ignore_errors: true

コールバックプラグインは、テスト行の代わりに診断行を出力します：

# command: 次のテストをセットアップ
ok - assert: 常にパスすることを確認

個別のテストケースとは異なり、この種類のタスクではエラーを無視したいとは思わないかもしれません。失敗はテストスイートのエラーを示し、テストの失敗を示すものではありません。

予期される失敗と予期しない成功

TAPは、実装されていない機能に対してテストを無視するためのTODOディレクティブをサポートしています。

TODOでマークされたテストが失敗した場合、TAPの消費者はそれを予期される失敗と見なします。同様に、TODOでマークされたテストが成功した場合、TAPの消費者はそれを予期しない成功と見なします。

予期される失敗にはTODOタグを付けます：

- name: 予期される失敗
  assert:
    that: false
  ignore_errors: true
  tags: TODO

これにより、TAPストリームに# TODOディレクティブが出力されます：

not ok - assert: 予期される失敗 # TODO

もしテストが成功すれば、予期しない成功の出力が得られます：

ok - assert: 予期される失敗 # TODO

テストをスキップする

TAPは、特定のテストを無視するためのSKIPディレクティブもサポートしています。

このコールバックは、Ansibleのwhenステートメントを使ってスキップされたテストを制御します：

- name: これはスキップされたタスクです
  assert:
    that: false
  ignore_errors: true
  when: false

テストをスキップした理由はテスト行に表示されます：

ok - assert: スキップされました # SKIP 条件チェックに失敗

例

tests/ディレクトリには、すべてのテスト結果を生成する例のテストスイートが含まれています。

プラグインをインストールした後、テストスイートを実行するには次のコマンドを使用します：

ANSIBLE_STDOUT_CALLBACK=tap ansible-playbook -i localhost, -c local tests/playbooks/test_multiple_with_failures.yml

以下のTAPストリームが得られます。これを任意のTAP消費者に渡すことができます。

TAP version 13
# command: 次のテストをセットアップ
ok - assert: パス
not ok - assert: 失敗
  ---
  _ansible_no_log: false
  _ansible_verbose_always: true
  assertion: false
  changed: false
  evaluated_to: false
  failed: true
  invocation:
    module_args:
      that: false
    module_name: assert
  ...
not ok - assert: 予期される失敗 # TODO
ok - assert: 予期しないパス # TODO
ok - assert: スキップされました # SKIP 条件チェックに失敗
1..5

注意事項

現時点では、このプラグインは一度に1つのホストに対してしかテストを実行できません。TAP仕様書では、複数の出力ストリームを組み合わせる方法を説明していません。

ライセンス

MIT