From e547abccea7b200fd14b9ea56481bf37a385b7cd Mon Sep 17 00:00:00 2001
From: Jesus Checa Hidalgo <jchecahi@redhat.com>
Date: Thu, 13 Jun 2024 17:59:13 +0200
Subject: [PATCH] Add tmt tests documentation

---
 README.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 93 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 006681f..a63f712 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,93 @@
-# Tests for rust packages
+# Rust Tests
+
+This repository contains tests for rust packages. These tests are meant to be
+run on bodhi updates or Pull Requests.
+
+## Usage
+Tests are executed using TMT (Test Management Tool). The repository includes a
+TMT plan that runs all the tests by default. All the tests support (and expect)
+the following context dimensions:
+
+* `distro`
+* `arch`
+* `collection` (only applicable to RHEL 7)
+
+To run the tests:
+```bash
+# Run in the default virtual environment
+tmt -c distro=<distro> -c arch=<arch> run -avv
+
+# Run on a scheduled system
+tmt -c distro=<distro> -c arch=<arch> run -avv provision -h connect -g <ip_or_hostname>
+
+# Run specific tests
+tmt -c distro=<distro> -c arch=<arch> run -avv provision -h connect -g <ip_or_hostname> test -n <regex>
+```
+
+## Adding New Tests
+Please consider the following when adding new tests:
+
+* Test scripts must be named `runtest.sh`.
+* Prefer using `beakerlib` tests over `shell` tests. If using a shell test
+cannot be avoided, the `main.fmf` file must redefine/overwrite the framework
+key by adding `framework: shell`.
+* Tests must be placed in `tests/<category>/<test-name>/`, where `<category>`
+can be `Regression`, `Sanity`, `Security`, or a new one if required.
+* This repository has a common configuration under `tests/main.fmf`, inherited
+by all tests. When adding new ones, be careful not to overwrite existing keys
+from the inherited `tests/main.fmf`.
+
+### Templates
+Use the following templates when creating new tests.
+
+FMF template. Uncomment needed fields, remove the rest.
+```yaml
+summary: Descriptive summary for the test
+duration: 2m
+tier: 1
+# Add an additional contact(s) if applicable
+# contact+:
+#   - Somebody <somebody@redhat.com>
+# Additional requires
+# require+:
+#   - rpm-build
+# Adjustments based on context dimensions
+# adjust+:
+#   - when: collection is defined
+#     enabled: false
+#     because: Test not supported in collections
+# link+:
+#   - verifies: https://issues.redhat.com/browse/...
+# tag+:
+#   - sometag
+```
+
+Script template:
+```bash
+# Include Beaker environment
+. /usr/share/beakerlib/beakerlib.sh || exit 1
+
+# Define package name(s) for rlAssertRpm to report installed versions
+PACKAGE=$(rpm -qf $(which rustc))
+PACKAGES=${PACKAGES:-$PACKAGE}
+
+rlJournalStart
+    rlPhaseStartSetup
+        rlAssertRpm --all
+        # Any additional setup steps.
+        # ....
+
+        rlRun "TmpDir=\$(mktemp -d)" 0 "Creating tmp directory"
+        rlRun "pushd $TmpDir"
+    rlPhaseEnd
+
+    rlPhaseStartTest
+        # Your actual test goes here
+    rlPhaseEnd
+
+    rlPhaseStartCleanup
+        rlRun "popd"
+        rlRun "rm -r $TmpDir" 0 "Removing tmp directory"
+    rlPhaseEnd
+rlJournalEnd
+```