From e1979f486c5ea4acffac8ba12adc9ef97a246623 Mon Sep 17 00:00:00 2001
From: Marcin Owsiany <porridge@redhat.com>
Date: Tue, 22 Aug 2023 10:34:11 +0200
Subject: [PATCH] Document test run label support.

Signed-off-by: Marcin Owsiany <porridge@redhat.com>
---
 content/docs/cli.md               |  6 ++++++
 content/docs/testing/reference.md | 25 +++++++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/content/docs/cli.md b/content/docs/cli.md
index 2da2e47..cf943c9 100644
--- a/content/docs/cli.md
+++ b/content/docs/cli.md
@@ -105,6 +105,12 @@ Start a KIND cluster for the tests (cannot be used with --start-control-plane).
 If set, the specific test case to run.
 :::
 
+::: flag --test-run-labels (string)
+Optional label set to associate with this test run.
+This label set can then be matched against by the `testRunSelector` in `TestFile` objects to optionally exclude selected files.
+The syntax is comma-separated list of key=value assignments.
+:::
+
 ::: flag -v or -vv (int)
 Logging verbosity level. 0=normal, 1=verbose, 2=detailed, 3 or more =trace.
 :::
diff --git a/content/docs/testing/reference.md b/content/docs/testing/reference.md
index af919b0..92133fb 100644
--- a/content/docs/testing/reference.md
+++ b/content/docs/testing/reference.md
@@ -113,6 +113,31 @@ timeout | int  | Number of seconds that the test is allowed to run for | 30
 collectors | list of [collectors](#collectors) | The collectors to be invoked to gather information upon step failure | N/A
 commands | list of [commands](#commands) | Commands to run prior to the beginning of the test step. | N/A
 
+## TestFile
+
+A `TestFile` object can be used to provide configuration concerning a single YAML test file that contains it.
+
+```yaml
+apiVersion: kuttl.dev/v1beta1
+kind: TestFile
+testRunSelector:
+  matchLabels:
+    flavor: vanilla
+```
+
+Supported settings:
+
+| Field           | Type           | Description                                                                                                                     | Default                                                      |
+|-----------------|----------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|
+| testRunSelector | label selector | If this selector does not match [labels of this test run](#test-run-labels-and-selectors), the containing file will be ignored. | Empty label selector (matches all possible test label sets). |
+
+
+### Test Run Labels and Selectors
+
+An invocation of `kuttl test` may specify a label set associated with a test run using a command line flag.
+One can then use a `TestFile` object with `testRunSelector` to decide whether a given test YAML file should be included
+in a test run or not.
+
 ## Collectors
 
 The `Collectors` object is used by the `TestAssert` object as a way to collect certain information about the outcome of an `assert` or `errors` step should it fail. A collector is only invoked in cases where a failure occurs and not if the step succeeds. Collection can occur from Pod logs, Namespace events, or the output of a custom command.