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
```bash
terraform test
```

#### Run Tests in Verbose Mode
```bash
terraform test -verbose
```

#### Run Specific Test File
```bash
terraform test -filter=tests/resource_groups.tftest.hcl
```

#### Run Specific Test Case
```bash
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

```hcl
# 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

```hcl
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](https://developer.hashicorp.com/terraform/language/tests)
- [Terraform Test Command](https://developer.hashicorp.com/terraform/cli/commands/test)
- [Writing Terraform Tests](https://developer.hashicorp.com/terraform/language/tests/syntax)