Skip to main content

Test a Module

Last updated on

Test module changes before teams adopt new versions. Harness Module Registry supports integration testing and native OpenTofu/Terraform testing through automated testing pipelines.

Integration testing provisions real infrastructure and destroys it after the test. OpenTofu/Terraform testing runs native test files against the module.

note

Setting up module testing does not run a test. Testing pipelines run when a pull request targets the configured branch or when you trigger a pipeline manually.

Before you begin​

  • Registered module: A module registered in the Harness IaCM Module Registry. Go to Register a Module to register a module.
  • Harness project access: Execute permissions on IaCM pipelines. Go to RBAC in Harness to configure roles.
  • Cloud provider connector (integration testing only): A connector with credentials to create and destroy real infrastructure. Go to Add an AWS connector to set up a connector.

Choose a testing method​

Integration testing validates your module against real infrastructure. Harness runs init → plan → apply → destroy for each example in the module's examples/ directory.

Add integration test cases​

To enable integration testing, add an examples/ directory to your module repository. Each subdirectory represents a test case and should contain a valid OpenTofu or Terraform configuration:

module-repository/
├── main.tf
├── variables.tf
├── outputs.tf
├── examples/              # Required for integration testing
│   ├── basic-example/     # Test case 1
│   │   ├── main.tf
│   │   ├── variables.tf   # Optional
│   │   └── outputs.tf     # Optional
│   └── advanced-example/  # Test case 2
│       ├── main.tf
│       ├── variables.tf   # Optional
│       └── outputs.tf     # Optional
└── README.md
Examples directory

Integration testing runs once for each subdirectory in examples/. If the examples/ directory is absent or contains no subdirectories, there are no integration test cases to run.

Configure the target branch​

Module testing uses the target branch configured when you register the module. A pull request targeting that branch triggers the module's configured testing pipelines. Go to Register a Module to set the target branch.

How module testing works​

A pull request against the configured branch triggers the testing pipeline through a webhook. The pipeline runs the IACM Module Test step and returns a pass or fail result for the module version.

The testing pipeline receives the module's moduleId as a runtime input through the webhook. In the pipeline YAML, moduleId is defined as <+input>, which makes the pipeline reusable across modules.

Example pipeline YAML​

The testing pipeline receives the module ID as a runtime input. In this example, IACM Module Test runs the integration-test command:

pipeline:
  name: iacm_integration_testing
  identifier: iacm_integration_testing
  projectIdentifier: project_77777
  orgIdentifier: org_66666
  description: Testing pipeline for module testing using integration-test
  stages:
    - stage:
        name: testing
        identifier: testing
        type: IACM
        spec:
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          moduleId: <+input>
          execution:
            steps:
              - step:
                  type: IACMModuleTestPlugin
                  name: IACMModuleTestPlugin_1
                  identifier: IACMModuleTestPlugin_1
                  spec:
                    command: integration-test
                  timeout: 100m
warning

Provisioning workspaces are not supported in module testing pipelines. Use the moduleId runtime input to identify the module under test. Adding a provisioning workspace stage causes execution to fail.

Requirements​

Integration testing requires a cloud provider connector. Integration tests create and destroy real infrastructure, so the connector provides the credentials required to provision the test resources.

OpenTofu/Terraform testing requires selecting a provisioner and version during setup (for example, OpenTofu 1.9.0). No cloud provider connector is required.

Set up module testing​

Set up testing from the Test Executions tab of the module you want to test. The setup wizard is titled Module Registry Testing Setup.

Credit usage​

tip

Harness-provided module testing pipelines do not consume workspace credits. Custom pipelines that use workspaces do consume credits.

ScenarioCredit usage
Default testing pipelines or custom pipelines using Harness stepsNo credits consumed
Custom pipelines using workspacesCredits consumed

Troubleshooting​

The module testing pipeline does not trigger when a pull request is opened against the configured branch in Harness IaCM

Confirm that the PR targets the exact branch configured during testing setup. Also verify that the webhook trigger is active on the testing pipeline by navigating to the pipeline's Triggers tab. If the trigger is missing or shows a Failed status, re-run the Module Registry Testing Setup wizard to recreate it.

The IACM Module Test step fails with a missing or invalid moduleId in Harness IaCM

The testing pipeline receives moduleId as a runtime input from the webhook trigger. Confirm that moduleId is defined as <+input> in the pipeline YAML and that you have not hardcoded a value. Do not add a provisioning workspace stage to the testing pipeline — this is not supported and causes execution to fail.

Integration tests fail during the apply step when testing a Harness IaCM module

Confirm that the cloud provider connector has sufficient permissions to create and destroy the resources defined in the examples/ directory. Each subdirectory in examples/ is treated as an independent test case. Check the pipeline execution logs for the specific resource error and verify that the connector credentials are valid.

Next steps​