add api tests and coverage metrics for all unit tests

.github/workflows/build-containers.yml

@@ -18,6 +18,17 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v6
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install Python test dependencies
+        run: pip install pytest pyyaml pytest-cov
+
+      - name: Run Python unit tests
+        run: pytest tests/ -v --cov=src --cov-report=xml --cov-report=term-missing
+
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
@@ -29,9 +40,17 @@ jobs:
         working-directory: webui
         run: npm ci
 
-      - name: Run WebUI tests
+      - name: Run WebUI tests with coverage
         working-directory: webui
-        run: npm test -- --run
+        run: npm run test:coverage -- --run
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml,webui/coverage/lcov.info
+          flags: python,webui
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
 
   build-and-push-images:
     runs-on: ubuntu-latest

.github/workflows/build-pr.yml

@@ -18,6 +18,17 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v6
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install Python test dependencies
+        run: pip install pytest pyyaml pytest-cov
+
+      - name: Run Python unit tests
+        run: pytest tests/ -v --cov=src --cov-report=xml --cov-report=term-missing
+
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
@@ -29,9 +40,17 @@ jobs:
         working-directory: webui
         run: npm ci
 
-      - name: Run WebUI tests
+      - name: Run WebUI tests with coverage
         working-directory: webui
-        run: npm test -- --run
+        run: npm run test:coverage -- --run
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml,webui/coverage/lcov.info
+          flags: python,webui
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
 
   build-images:
     runs-on: ubuntu-latest

.github/workflows/build-release.yml

@@ -19,6 +19,17 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v6
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install Python test dependencies
+        run: pip install pytest pyyaml pytest-cov
+
+      - name: Run Python unit tests
+        run: pytest tests/ -v --cov=src --cov-report=xml --cov-report=term-missing
+
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
@@ -30,9 +41,17 @@ jobs:
         working-directory: webui
         run: npm ci
 
-      - name: Run WebUI tests
+      - name: Run WebUI tests with coverage
         working-directory: webui
-        run: npm test -- --run
+        run: npm run test:coverage -- --run
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml,webui/coverage/lcov.info
+          flags: python,webui
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
 
   build-and-push-images:
     runs-on: ubuntu-latest

.gitignore

@@ -24,3 +24,10 @@ Thumbs.db
 /src/v5_4/__pycache__/
 /src/v5_5/__pycache__/
 /contrib/devportal/redocly/src/__pycache__/
+
+# Test coverage artifacts #
+###########################
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/

CONTRIBUTING.md

@@ -20,6 +20,29 @@ To suggest a feature or enhancement, please create an issue on GitHub with the l
 
 - Fork the repo, create a branch, implement your changes, add any relevant tests, submit a PR when your changes are **tested** and ready for review.
 
+## Running Tests
+
+### Python unit tests
+
+Run from the repository root:
+
+```bash
+pip3 install pytest pyyaml pytest-cov
+python3 -m pytest tests/ -v --cov=src --cov-report=term-missing
+```
+
+### WebUI tests
+
+Run from the `webui/` directory:
+
+```bash
+cd webui
+npm install
+npm test -- --run
+```
+
+Both suites are run automatically in GitHub Actions. A failing test will block CI builds.
+
 ## Code Guidelines
 
 ### Git Guidelines

README.md

@@ -1,6 +1,7 @@
 # NGINX-Declarative-API
 
 [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![codecov](https://codecov.io/gh/f5devcentral/NGINX-Declarative-API/branch/main/graph/badge.svg)](https://codecov.io/gh/f5devcentral/NGINX-Declarative-API)
 
 NGINX Declarative API enables users to manage **NGINX configurations** in a modern **declarative style**. Instead of modifying configurations manually or using low-level APIs, this project simplifies operational workflows by allowing users to express desired configurations as a single JSON object.
 The API abstracts the complexity of managing NGINX configurations, empowering developers, operators, and automation systems to integrate seamlessly with NGINX.
@@ -227,6 +228,25 @@ NGINX Declarative API can be deployed on:
 * Kubernetes using [manifests](/contrib/kubernetes)
 * Kubernetes using a [Helm chart](contrib/helm/nginx-declarative-api)
 
+## 🧪 Running unit tests
+
+Python unit tests cover the core utility and configuration-patching modules. Run them from the repository root:
+
+```bash
+pip3 install pytest pyyaml
+python3 -m pytest tests/ -v
+```
+
+WebUI tests use [Vitest](https://vitest.dev/) and can be run from the `webui/` directory:
+
+```bash
+cd webui
+npm install
+npm test -- --run
+```
+
+Both test suites run automatically in GitHub Actions on every pull request and release build.
+
 ## 🐳 Building Docker images
 
 Docker images can be built and run using the Docker compose [script](/contrib/docker-compose) provided

tests/conftest.py

@@ -0,0 +1,7 @@
+"""
+Add src/ to sys.path so tests can import project modules without installing them.
+"""
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))