Add documentation to HACKING.rst describing idempotent_id
All Tempest tests require an idempotent_id decorator to uniquely
identify test functionlity. Previously this requirement was not
documented, leading to some confusion regarding its use and
implemtation. This patch includes documentation in the HACKING.rst
file that describes the purpose, format, and tool for working
with idempotent_id metadata.
Change-Id: I569bb68adc498f428664ed0b49d5943a353124b9
diff --git a/HACKING.rst b/HACKING.rst
index c776c49..45c35df 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -314,6 +314,39 @@
* Check written content in the instance booted from snapshot
"""
+Test Identification with Idempotent ID
+--------------------------------------
+
+Every function that provides a test must have an ``idempotent_id`` decorator
+that is a unique ``uuid-4`` instance. This ID is used to complement the fully
+qualified test name and track test funcionality through refactoring. The
+format of the metadata looks like::
+
+ @test.idempotent_id('585e934c-448e-43c4-acbf-d06a9b899997')
+ def test_list_servers_with_detail(self):
+ # The created server should be in the detailed list of all servers
+ ...
+
+Tempest includes a ``check_uuid.py`` tool that will test for the existence
+and uniqueness of idempotent_id metadata for every test. By default the
+tool runs against the Tempest package by calling::
+
+ python check_uuid.py
+
+It can be invoked against any test suite by passing a package name::
+
+ python check_uuid.py --package <package_name>
+
+Tests without an ``idempotent_id`` can be automatically fixed by running
+the command with the ``--fix`` flag, which will modify the source package
+by inserting randomly generated uuids for every test that does not have
+one::
+
+ python check_uuid.py --fix
+
+The ``check_uuid.py`` tool is used as part of the tempest gate job
+to ensure that all tests have an ``idempotent_id`` decorator.
+
Branchless Tempest Considerations
---------------------------------