From 8947089114e615619ae48f3a0ac9b9899defa72e Mon Sep 17 00:00:00 2001
From: zpetrace <zpetrace@redhat.com>
Date: Wed, 14 Aug 2024 16:30:51 +0200
Subject: [PATCH] feat(workflow): Adding a GitHub workflow for test docstrings
 validation

- Introduced a new GitHub Actions workflow (`docstring_validation.yml`) to validate docstrings using Betelgeuse. This workflow triggers on pull requests affecting the `integration-tests/` directory and performs a dry run with Betelgeuse.
- Added a `README.md` to the `integration-tests/` directory, documenting how to run Betelgeuse for generating and importing test-case and test-run XML files.
- Created a custom Betelgeuse configuration (`custom_betelgeuse_config.py`) to define additional fields for test cases, ensuring proper parsing of docstrings in the `integration-tests/` directory.
---
 .github/workflows/docstring_validation.yml    | 29 +++++++++
 integration-tests/README.md                   | 64 +++++++++++++++++++
 integration-tests/custom_betelgeuse_config.py | 15 +++++
 3 files changed, 108 insertions(+)
 create mode 100644 .github/workflows/docstring_validation.yml
 create mode 100644 integration-tests/README.md
 create mode 100644 integration-tests/custom_betelgeuse_config.py

diff --git a/.github/workflows/docstring_validation.yml b/.github/workflows/docstring_validation.yml
new file mode 100644
index 00000000..bd24043b
--- /dev/null
+++ b/.github/workflows/docstring_validation.yml
@@ -0,0 +1,29 @@
+---
+name: Test Docstrings Validation
+
+on:
+  pull_request:
+    paths:
+      - "integration-tests/**"
+
+jobs:
+  betelgeuse:
+    name: "betelgeuse dry-run"
+    runs-on: ubuntu-latest
+    container:
+      image: fedora:latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Base setup for Betelgeuse
+        run: |
+          dnf --setopt install_weak_deps=False install -y \
+              python3-pip
+          python3 -m pip install betelgeuse
+
+      - name: Run Betelgeuse
+        run: |
+          PYTHONPATH=integration-tests/ betelgeuse --config-module \
+            custom_betelgeuse_config test-case --dry-run \
+            integration-tests/ dryrun_project ./test_case.xml
diff --git a/integration-tests/README.md b/integration-tests/README.md
new file mode 100644
index 00000000..71686f0b
--- /dev/null
+++ b/integration-tests/README.md
@@ -0,0 +1,64 @@
+# Running Betelgeuse
+
+### Docs:
+https://betelgeuse.readthedocs.io/en/stable/
+https://betelgeuse.readthedocs.io/en/stable/config.html
+
+## Test-case command
+Command generates an XML file suited to be imported by the **Test Case XML Importer**. It reads the Python test suite source code and generated XML file with all the information necessary.
+
+The `test-case` requires:
+
+- The path to the Python test suite source code
+- The Polarion project ID
+- The output XML file path (will be overwritten if exists)
+
+
+There shoud also be a custom config file specified for pythonpath for Betelgeuse to correctly read all the custom fields in the docstrings. The file is saved in integration-tests/custom_betelgeuse_config.py
+
+Example:
+
+```console
+$ PYTHONPATH=integration-tests/ \
+    betelgeuse --config-module \
+    custom_betelgeuse_config test-case \
+    integration-tests/ PROJECT ./test_case.xml
+```
+
+This will create a test_case.xml file in integration-tests/
+
+## Test-run command
+Command generates an XML file suited to be imported by the **Test Run XML Importer**.
+
+It takes:
+
+- A valid xUnit XML file
+- A Python test suite where test case IDs can be found
+
+And generates a resulting XML file with all the information necessary.
+
+It requires:
+
+- The path to the xUnit XML file
+- The path to the Python test suite source code
+- The Polarion user ID
+- The Polarion project ID
+- The output XML file path (will be overwritten if exists)
+
+It is also highly recommended to use `--response-property` as it will then be easier to monitor the importer messages
+
+Example:
+
+```console
+$ PYTHONPATH=integration-tests/ \
+    betelgeuse test-run \
+    --response-property property_key=property_value \
+    junit.xml \
+    insights-client/integration-tests \
+    testuser \
+    betelgeuse-test-run.xml
+```
+
+NOTE:
+
+`--dry-run` can be used with `test-run` command when testing the functionality.
\ No newline at end of file
diff --git a/integration-tests/custom_betelgeuse_config.py b/integration-tests/custom_betelgeuse_config.py
new file mode 100644
index 00000000..19735d56
--- /dev/null
+++ b/integration-tests/custom_betelgeuse_config.py
@@ -0,0 +1,15 @@
+from betelgeuse import default_config
+
+TESTCASE_CUSTOM_FIELDS = default_config.TESTCASE_CUSTOM_FIELDS + (
+    "casecomponent",
+    "requirement",
+    "subsystemteam",
+    "tier",
+    "reference",
+)
+
+DEFAULT_CASECOMPONENT_VALUE = ""
+DEFAULT_REQUIREMENT_VALUE = ""
+DEFAULT_SUBSYSTEMTEAM_VALUE = ""
+DEFAULT_TIER_VALUE = ""
+DEFAULT_REFERENCE_VALUE = ""