TPA custom tests
================

環境とアプリケーションに固有の詳細なテストを簡単に定義して、TPAの
 :ref:`builtin tests <tpaexec test>`  を補強できます。

どんなに単純なタスクであっても、クラスターで実行するテストを作成して、すべてが期待どおりに機能していることを確認することを強くお勧めします。このようなテストを実行する統一された反復可能な方法を使用すると、危機に対処している場合でも、日常的なクラスター管理を行っている場合でも、重要なことを見逃すことはありません。

構成されたロール（またはその他のプロパティ）でクラスターインスタンスをターゲットとするテストを作成すると、該当するすべてのテストが適切なインスタンスで実行されることを確認できます。レプリケーションステータスを確認するレプリカの数、pgbouncerを実行しているサーバー、または手動で確認しているときに間違いを犯すように誘うその他の詳細を調べたり覚えたりする必要はありません。

テストでは、クラスターに重要な変更を加えてはなりません。実稼働サーバーで行うことを考えない場合は、おそらくテストに使用しないでください。

クイックスタート
----------------

-  クラスターディレクトリ内に\ ``tests/mytest.yml`` を作成します

-  ``tpaexec test /path/to/cluster mytest`` を実行します

``tpaexec test`` に\ ``--include-tests-from /other/path``
オプションを使用して、他の場所でテストを作成し、クラスター間でそれらを使用することもできます。

（使用方法については、 ``tpaexec help test`` を実行してください。）

例
--

すべてのPostgresインスタンスで実行されるテストの書き方は次のとおりです（\ ``hosts: all``
ではなく\ ``hosts: role_postgres`` に注意してください）。

任意のAnsibleタスクを使用して、クラスターから情報を収集し、テストを実行できます。いくつかの期待が満たされない場合に失敗するタスク（\ ``assert``
、\ ``fail … when`` など）を書くだけです。

.. code:: yaml

   - --

   -  name: Perform my custom tests
     hosts: role_postgres
     tasks:

     # Always start with this
     - include_role:
         name: test
         tasks_from: prereqs.yml

     # Make sure that the PGDATA/PG_VERSION file exists. (This is just a
     # simplified example, not something that actually needs testing.)
     - name: Perform simple test
       command: "test -f {{ postgres_data_dir }}/PG_VERSION"
       become_user: "{{ postgres_user }}"
       become: yes

     - name: Run pg_controldata
       command: >
         {{ postgres_bin_dir }}/pg_controldata {{ postgres_data_dir }}
       register: controldata
       become_user: "{{ postgres_user }}"
       become: yes

     # Write output to clusterdir/$timestamp/$hostname/pg_controldata.txt
     - name: Record pg_controldata output
       include_role:
           name: test
           tasks_from: output.yml
       vars:
         output_file: pg_controldata.txt
         content: |
           {{ controldata.stdout }}

上記のようにビルトイン\ ``output.yml``
を使用して、クラスターディレクトリのタイムスタンプ付きのテストディレクトリに任意のテスト出力を記録できます。

各テストは、完全なAnsibleプレイブック（つまり、単なるタスクのリストではなく、プレイのリスト）である必要があります。基本的なTPAセットアップタスクの後にインポートされ、実行されます。

破壊テスト
----------

テストは、デフォルトでは、クラスターに重要な変更を加えるべきではありません。
（レプリケーションをテストするテーブルを作成するようなことをする場合でも、自分自身のクリーンアップに注意する必要があります。）

実稼働クラスターで受け入れられない変更をクラスターに行うテストは、
``destructive``
としてマークしなければなりません。これらは、開発時、または初期クラスターの「バーンイン」プロセス中にのみ実行するテストである場合があります。

テストに\ ``prereqs.yml`` を含めるときに\ ``destructive: yes``
を設定することにより、「破壊的な」テストを定義できます。

.. code:: yaml


   - hosts: …
     tasks:
     - include_role:
         name: test
         tasks_from: prereqs.yml
       vars:
         destructive: yes

その後、誰かが\ ``tpaexec test /path/to/cluster mytest`` を実行すると、
``--destroy-this-cluster``
オプションを使用して実行を確認するように求めるエラーが表示されます。

（注： ``--destroy-this-cluster``
を使用することは、コマンドを実行するリスクを認識していることを意味します。テストによって実際にクラスターが破壊されることを保証するものではありません。）