// Use when running OPA policy unit tests, BATS bash tests, shellcheck, hadolint, or conftest integration tests locally. Covers test commands, coverage requirements, test data, and prerequisites.
| name | running-tests-locally |
| description | Use when running OPA policy unit tests, BATS bash tests, shellcheck, hadolint, or conftest integration tests locally. Covers test commands, coverage requirements, test data, and prerequisites. |
Tests are split into OPA Rego unit tests (policies/), BATS bash tests (utils.sh), conftest integration tests (policy/data integration), and linters (shellcheck, hadolint, yamllint).
| Command | What it does |
|---|---|
opa test policies unittests unittests/test_data -c | OPA policy unit tests with coverage |
bats unittests_bash | All BATS bash unit tests |
shellcheck -s bash test/utils.sh | Lint bash functions |
hadolint Dockerfile | Lint Dockerfile (ignore DL3003,DL3013,DL3041,DL4006) |
yamllint . | Lint all YAML files |
Prerequisites: install opa binary (v0.56.0 used in CI)
Command: opa test policies unittests unittests/test_data -c
Coverage requirement: 100% — every line of policy code must be covered by at least one test. CI enforces this with jq assertion: coverage >= 100.00.
Coverage reporting:
opa test --coverage --format json policies unittests unittests/test_data \
| opa eval --data hack/simplecov.rego data.simplecov.from_opa > coverage.json
This generates codecov-compatible JSON for CI upload.
Prerequisites: bats v1.8.2, jq, cosign
Run all tests:
bats unittests_bash
Run single test file:
bats unittests_bash/test_utils.bats
Run tests matching pattern:
bats unittests_bash/test_utils.bats -f "test name pattern"
Tests source test/utils.sh directly and mock external tools (skopeo, opm, cosign).
File: test/conftest.sh (BATS format, separate from unit tests)
Setup:
export POLICY_PATH=policies
Run:
bats test/conftest.sh
Tests the actual conftest CLI invocation against real policies, not just Rego logic. Uses three namespaces:
--namespace required_checks — blocking policies--namespace optional_checks — advisory policies--namespace fbc_checks — FBC-specific policiesFile: test/selftest.sh
Validates the built Docker image has:
Run inside the container after building the image (automated in integration test pipeline).
Shellcheck:
shellcheck -s bash test/utils.sh
Ignores conftest.sh and selftest.sh (they have special formats).
Hadolint:
hadolint Dockerfile
Ignores rules: DL3003, DL3013, DL3041, DL4006
Yamllint:
yamllint .
Uses .yamllint config, ignores /vendor.
| Problem | Fix |
|---|---|
| OPA coverage < 100% | Add test for every policy rule and helper function |
| BATS test fails "command not found" | Install prerequisites: jq, cosign, bats 1.8.2 |
| Shellcheck SC2086 | Quote variables: "${var}" not $var |
| OPA test "undefined ref" | Check import path matches test_data filename (no extension) |
| conftest.sh fails | Set export POLICY_PATH=policies before running |
Use when adding new tools, binaries, or packages to the konflux-test container image. Covers artifacts.lock.yaml (generic binaries), rpms.in.yaml (system packages), multi-architecture support, and hermetic build constraints.
Use when CI checks fail unexpectedly, when preparing code for CI, or when encountering non-obvious build and pipeline behavior. Covers hermetic builds, Tekton pipelines, multi-arch, GitHub Actions checks, and integration test structure.
Use when preparing a pull request for review or before pushing. Checklist of commit conventions, Rego policy tests at 100% coverage, BATS tests, code quality checks, and CI check requirements.
Use when adding or modifying bash utility functions in test/utils.sh. Covers naming conventions, function structure, BATS tests, mock patterns for external tools, TEST_OUTPUT format, and shellcheck compliance.
Use when writing, modifying, or reviewing OPA/conftest Rego policies. Covers package naming, rule prefixes (violation_ and warn_), conftest namespaces, violation object structures, imports, and unit test patterns.