Package Testing

What you’ll accomplish

You’ll set up a testing strategy for your UDS Package that validates deployment correctness, UDS Core integration, and upgrade compatibility. These practices ensure packages deploy reliably and integrate properly with core services like Istio and Keycloak.

Prerequisites

UDS CLI installed
A UDS Package ready for testing
Node.js installed (for Playwright and Jest)
yamllint installed (for linting YAML files)
Shellcheck installed (for linting bash scripts)

Before you begin

UDS Package testing focuses on validating packaging, deployment, and integration, not duplicating upstream application tests. Tests should confirm that your packaging and configuration choices don’t break key functionality, and that integration with UDS Core components works as expected.

Place all test files (Playwright specs, Jest tests, custom validation scripts, and related configuration) in a tests directory at the root of your package repository.

Steps

Add journey tests

Journey tests validate the critical workflows impacted by your packaging, configuration, or deployment. Focus on deployment-related concerns like network policies, SSO access, and cluster resource access rather than upstream application logic.

Use Playwright for UI testing and Jest for API or non-UI testing. Use bash or other scripting languages for custom validation scripts as needed.

The UDS Package Template includes Playwright stubs in the tests/ directory to get you started.

Keep journey tests small and focused. Validate deployment and UDS integration; avoid duplicating upstream unit or feature tests.

If licensing or other constraints prevent a flow from running in CI, document the limitation and implement the most realistic validation available.
Add upgrade tests

Upgrade tests validate that the current development package deploys successfully over the most recently released version. When writing upgrade tests, verify the following:
- Data migration and persistence work correctly
- Configurations carry over or update properly
- No breaking changes occur in APIs or external integrations
The UDS Package Template provides a default test-upgrade task you can use directly in your CI workflows.
Add linting and static analysis

Run linting checks to catch issues before deployment.
Terminal window
```
# Lint Zarf package definitions
uds zarf dev lint # https://docs.zarf.dev/commands/zarf_dev_lint/

# Lint YAML files
yamllint .

# Lint bash scripts
shellcheck scripts/*.sh
```
By using uds-common, you can run uds run lint:yaml|shell|all from the directory root to execute these checks.
Integrate tests into CI/CD

Configure your pipeline to run all tests automatically so every code change is verified before advancing through the workflow. Follow these principles for reliable test suites:
- Repeatability: Tests should produce consistent results regardless of execution order or frequency. Design them to handle dynamic and asynchronous workloads without compromising output integrity.
- Error handling: Fail with actionable messages and include enough context to debug.
- Performance: Balance coverage with rapid feedback to keep pipelines efficient.
The UDS Package Template includes default GitHub Actions CI/CD workflows you can use as a starting point or reference.

Verification

Define your test tasks in a tasks/test.yaml file to automate and simplify test execution. A well-structured test file groups health checks, ingress validation, and UI tests into individual tasks, with an all task that runs them in sequence:

tasks:
  - name: all
    actions:
      - task: health-check
      - task: ingress
      - task: ui

  - name: health-check
    actions:
      - description: Verify deployment is available
        wait:
          cluster:
            kind: Deployment
            name: my-package
            namespace: my-package
            condition: Available

  - name: ingress
    actions:
      - description: Verify ingress returns 200
        maxRetries: 30
        cmd: |
          STATUS=$(curl -L -o /dev/null -s -w "%{http_code}\n" https://my-package.uds.dev)
          echo "Status: ${STATUS}"
          if [ "$STATUS" != "200" ]; then
            sleep 10
            exit 1
          fi

  - name: ui
    description: Run Playwright UI tests
    actions:
      - cmd: npx playwright test
        dir: tests

With this in place, you can run all tests with a single command:

uds run test:all

See the Reference Package test tasks for a complete example.

Success criteria

Your test suite is working correctly when:

All tasks in uds run test:all exit with code 0
No error output appears in health check, ingress, or UI task logs
Journey tests pass consistently across multiple runs
Upgrade tests confirm data persists and the package reaches a Ready state after upgrade

Troubleshooting

Problem: Journey tests fail intermittently

Symptom: Tests pass locally but fail in CI due to timing or async workloads.

Solution: Add appropriate wait conditions or retries for dynamic resources. Ensure tests don’t depend on execution order.

Problem: Upgrade tests fail on data migration

Symptom: Data from the previous version is missing or corrupted after upgrade.

Solution: Check that persistent volume claims and database migrations are handled correctly in your Zarf package lifecycle actions.