# Local Terraform Testing

This document provides guidance on how to test Terraform modules locally during development, allowing you to iterate quickly without publishing modules to Terraform Cloud.

## 📋 Overview

Local testing allows you to:

- ✅ Test module changes before publishing to Terraform Cloud
- 🐛 Debug module issues more efficiently
- 🚀 Develop and validate new module features locally
- 🌍 Ensure module compatibility across different environments

## ✅ Prerequisites

- 💻 Terraform installed locally
- 📁 Access to the module source code
- ☁️ Access to Terraform Cloud workspace (credentials handled by Terraform Cloud)
- 📖 Understanding of [swap-terraform-modules.md](swap-terraform-modules.md) process

## 🎯 Step 1: Prepare Your Local Environment

1. 📥 Clone or pull the latest version of the module repository
2. 📂 Ensure you have the module code locally (e.g., `c:\forge\src\terraform\saif-web-service`)
3. 🔐 Verify your Terraform Cloud workspace access is configured

## 🔄 Step 2: Modify Module Source

### ☁️ Before (Terraform Cloud Module)

```hcl
module "api-service" {
  source  = "app.terraform.io/SAIFCorp/api-service/saif"
  version = "~>2.1.0"
  # insert required variables here
  project_id = var.project_id
  environment = var.environment
}
```

### 💻 After (Local Module)

```hcl
module "api-service" {
  source = "c:\\forge\\src\\terraform\\saif-api-service"
  # Note: Remove version constraint for local modules
  # insert required variables here
  project_id = var.project_id
  environment = var.environment
}
```

## 📚 Step 3: Common Local Module Patterns

### 🌐 Web Service Module

```hcl
# From Terraform Cloud
module "web-service" {
  source  = "app.terraform.io/SAIFCorp/web-service/saif"
  version = "~>2.1.0"
  # variables...
}

# To Local
module "web-service" {
  source = "c:\\forge\\src\\terraform\\saif-web-service"
  # variables...
}
```

### 🔌 API Service Module

```hcl
# From Terraform Cloud
module "api-service" {
  source  = "app.terraform.io/SAIFCorp/api-service/saif"
  version = "~>2.1.0"
  # variables...
}

# To Local
module "api-service" {
  source = "c:\\forge\\src\\terraform\\saif-api-service"
  # variables...
}
```

### 🔒 Security Module

```hcl
# From Terraform Cloud
module "security" {
  source  = "app.terraform.io/SAIFCorp/security/azure//modules/application"
  version = "~>2.1.0"
  # variables...
}

# To Local
module "security" {
  source = "c:\\forge\\src\\terraform\\azure-security\\modules\\application"
  # variables...
}
```

## 🧪 Step 4: Testing Process

1. **🚀 Initialize Terraform**

   ```powershell
   terraform init
   ```

2. **📋 Plan Changes**

   ```powershell
   terraform plan
   ```

3. **⚡ Apply Changes (if safe)**

   ```powershell
   terraform apply
   ```

4. **✅ Validate Results**
   - 🔍 Check Azure resources in the portal
   - ✔️ Verify expected behavior
   - 🧪 Test application functionality

## ⚠️ Step 5: Important Considerations

### 📁 Path Separators

- 🖥️ Use double backslashes (`\\`) or forward slashes (`/`) in Windows paths
- 💡 Example: `c:\\forge\\src\\terraform\\module-name` or `c:/forge/src/terraform/module-name`

### 🏷️ Version Constraints

- ❌ **Remove version constraints** when using local modules
- 🚫 Local modules don't support version pinning
- 📍 Version is implicit based on your local code state

### 📍 Relative vs Absolute Paths

```hcl
# 👍 Absolute path (recommended)
source = "c:\\forge\\src\\terraform\\saif-web-service"

# ⚠️ Relative path (use with caution)
source = "..\\..\\saif-web-service"
```

## 🔄 Step 6: Switch Back to Terraform Cloud

**⚠️ CRITICAL: Always switch back to Terraform Cloud modules before committing!**

After testing, revert your changes:

```hcl
# Switch back from local
module "api-service" {
  source = "c:\\forge\\src\\terraform\\saif-api-service"
  # variables...
}

# To Terraform Cloud
module "api-service" {
  source  = "app.terraform.io/SAIFCorp/api-service/saif"
  version = "~>2.1.0"
  # variables...
}
```

## 💡 Best Practices

### 1. 🌿 Use Git Branches

- 🔀 Create a feature branch for local testing
- 🏗️ Keep local module changes separate from production code

### 2. 📝 Document Changes

- 📋 Keep track of what you're testing
- 📄 Document any temporary modifications

### 3. 🧩 Test Incrementally

- 👶 Test small changes first
- ✅ Validate each change before proceeding

### 4. 🧹 Clean Up

- 🔄 Always revert to Terraform Cloud modules
- 🗑️ Remove any temporary test resources

### 5. ✅ Validate Before Commit

```powershell
# Ensure you're back to using Terraform Cloud modules
Select-String -Path "*.tf" -Pattern "source.*c:\\\\"
# Should return no results before committing
```

## 🛠️ Troubleshooting

### 🚨 Common Issues

1. **📂 Path Not Found**
   - 🔍 Verify the local module path exists
   - ✔️ Check path separator usage (use `\\` or `/`)

2. **🔗 Module Dependencies**
   - 📦 Ensure all nested modules are available locally
   - 🔄 Update nested module sources if needed

### 🔧 Recovery Steps

If you encounter state issues:

1. **🔄 Reinitialize if needed**

   ```powershell
   terraform init -reconfigure
   ```

## 📚 Related Documentation

- 📖 [swap-terraform-modules.md](swap-terraform-modules.md) - Process for swapping module sources
- 📋 Terraform Module Development Guidelines

## 📝 Summary

Local Terraform module testing is a powerful development technique that allows for rapid iteration and debugging. Remember to:

1. 🖥️ Use proper path syntax for your operating system
2. 🚫 Remove version constraints for local modules
3. 🧪 Test thoroughly before publishing changes
4. ⚠️ **Always switch back to Terraform Cloud modules before committing**

This approach enables efficient module development while maintaining production stability.