terraform-vsphere-resourcegroups/TESTING.md

Terraform Testing Guide

This document describes the testing strategy and approach for the vSphere Resource Groups Terraform module.

Overview

This module uses Terraform's native testing framework (introduced in Terraform 1.6.0) to ensure code quality and correctness. Tests are organized into multiple test files, each focusing on different aspects of the module's functionality.

Test Structure

tests/
├── resource_groups.tftest.hcl        # Tests for default resource group creation
├── custom_configuration.tftest.hcl   # Tests for custom configurations
├── variable_validation.tftest.hcl    # Tests for variable validation and edge cases
└── setup/
    └── main.tf                       # Mock provider setup for testing

Test Coverage

1. Default Resource Groups (resource_groups.tftest.hcl)

Tests the default behavior when using the module without custom configuration:

• Default Resource Groups Creation: Verifies all 5 default resource groups (kubernetes, docker, infra, databases, app-servers) are created
• Shares Mapping Logic: Validates the local shares_mapping values (low=500, normal=1000, high=2000)
• Tag Categories: Ensures Environment and ResourceGroupType tag categories are properly configured
• Resource Group Tags: Verifies tags are created for each resource group
• Default Configurations: Validates default CPU/memory settings (expandable, no limits, no reservations)
• Output Validation: Ensures all outputs are generated correctly
• Naming Conventions: Verifies resource pools have correct display names

2. Custom Configuration (custom_configuration.tftest.hcl)

Tests advanced configuration scenarios:

• High Priority Resources: Custom CPU/memory reservations, limits, and high priority shares
• Low Priority Resources: Validates low priority share allocation
• Non-Expandable Resources: Tests fixed resource allocation (non-expandable)
• Multiple Custom Groups: Validates creating multiple resource groups with different priorities
• Environment-Specific Configuration: Tests environment variable integration
• Edge Cases: Single resource group scenario

3. Variable Validation (variable_validation.tftest.hcl)

Tests input variable validation and edge cases:

• Environment Values: Validates accepted environment values
• Variable Types: Ensures variables accept correct data types
• Resource Groups Structure: Validates the resource_groups map structure
• Optional Parameters: Verifies default values are applied correctly
• Shares Value Mapping: Tests all three share levels (low, normal, high)
• Empty Configuration: Handles empty resource_groups map
• Resource Limits: Validates CPU/memory limits configuration

Running Tests

Locally

Run All Tests

terraform test

Run Tests in Verbose Mode

terraform test -verbose

Run Specific Test File

terraform test -filter=tests/resource_groups.tftest.hcl

Run Specific Test Case

terraform test -filter=tests/resource_groups.tftest.hcl -verbose -test-directory=tests

In CI/CD Pipeline

Tests are automatically executed in the CI/CD pipeline as part of the terraform-test job:

1. Format Check: Validates Terraform formatting (terraform fmt -check -recursive)
2. Test Execution: Runs all tests with verbose output
3. Test Report: Generates and uploads test results as artifacts

The test job runs after security scanning (Checkov) and before SonarQube analysis.

Test Execution Flow

┌─────────────┐
│   TFLint    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Tfsec     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Checkov   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Terraform   │
│    Test     │ ◄── New Step
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ SonarQube   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Terraform   │
│    Init     │
└─────────────┘

Writing New Tests

Test File Structure

# Test description
run "test_name" {
  command = plan  # or apply

  # Optional: Override variables
  variables {
    environment = "dev"
    resource_groups = {
      custom = {
        name = "Custom Group"
      }
    }
  }

  # Assertions
  assert {
    condition     = <boolean_expression>
    error_message = "Descriptive error message"
  }
}

Best Practices

1. Use Descriptive Test Names: Test names should clearly describe what they're testing
2. One Concern Per Test: Each test should focus on a single aspect or scenario
3. Clear Error Messages: Error messages should explain what failed and why
4. Use Variables for Flexibility: Override variables to test different scenarios
5. Test Edge Cases: Include tests for empty inputs, minimum/maximum values, etc.
6. Use plan Command: Most tests should use command = plan to avoid requiring actual infrastructure

Example Test Pattern

run "validate_cpu_shares_mapping" {
  command = plan

  variables {
    resource_groups = {
      test_group = {
        name = "Test"
        cpu_shares = "high"
      }
    }
  }

  assert {
    condition = vsphere_resource_pool.resource_groups["test_group"].cpu_shares == 2000
    error_message = "High CPU shares should map to 2000"
  }
}

Test Requirements

• Terraform Version: >= 1.6.0 (required for native testing framework)
• Provider Version: vsphere ~> 2.10
• Mock Data: Tests use mock values for Vault credentials and vSphere resources

Troubleshooting

Test Failures

1. Review Test Output: Use -verbose flag for detailed output
2. Check Assertions: Verify the condition logic is correct
3. Validate Variables: Ensure variable values match expected types
4. Review Changes: If tests fail after code changes, review the modifications

Common Issues

Tests Skip Provider Validation

Tests use mock credentials (TF_VAR_role_id and TF_VAR_secret_id) to avoid requiring actual infrastructure access during testing.

Format Check Failures

Run terraform fmt -recursive to automatically format all Terraform files.

Test Hangs or Times Out

This may indicate a provider authentication issue. Ensure mock credentials are properly set in the test environment.

Test Metrics

Current test coverage includes:

• Total Test Files: 3
• Total Test Cases: 20+
• Areas Covered:
  • Resource creation and configuration
  • Tag management
  • Variable validation
  • Edge cases and error handling
  • Output generation

Integration with Quality Gates

Tests are part of the overall quality assurance strategy:

1. TFLint: Code style and best practices
2. Tfsec: Security scanning
3. Checkov: Security and compliance checks
4. Terraform Test: Functional correctness ⬅ New
5. SonarQube: Code quality analysis
6. Terraform Plan: Actual infrastructure validation

Future Improvements

Potential enhancements to the testing strategy:

• Add mock providers for complete isolation from infrastructure
• Implement test coverage reporting
• Add performance tests for large numbers of resource groups
• Create integration tests with actual vSphere environment
• Add contract tests for output structures
• Implement property-based testing for resource configurations

References

• Terraform Testing Documentation
• Terraform Test Command
• Writing Terraform Tests