InfraSpec

✅ Test your AWS infrastructure code in plain English.

_{100x faster tests • 90% cost savings • Zero cleanup}

---

Testing infrastructure shouldn't require learning complex testing frameworks or writing hundreds of lines of code. InfraSpec lets you write infrastructure tests in plain English using the battle-tested Gherkin syntax.

Traditional infrastructure testing solutions like Terratest require programming knowledge, so writing the tests can take as long as writing the infrastructure itself. They also limit collaboration so non-technical stakeholders can’t review or contribute, and tests often become difficult to maintain or understand over time.

InfraSpec combines a rich library of pre-built testing patterns with natural language specifications. Write tests that read like documentation and are executable from day one.

⚡ Quick Example

Here's how easy it is to test a Terraform S3 bucket configuration:

Feature: S3 Bucket Creation
  As a DevOps Engineer
  I want to create an S3 bucket with security guardrails
  So that I can store my data securely

  Scenario: Create a secure S3 bucket
    Given I have a Terraform configuration in "./examples/aws/s3/s3-bucket"
    And I set variable "bucket_name" to "my-data-bucket" with a random suffix
    When I run Terraform apply
    Then the S3 bucket from output "bucket_name" should exist
    And the S3 bucket from output "bucket_name" should have versioning enabled
    And the S3 bucket from output "bucket_name" should have a public access block
    And the S3 bucket from output "bucket_name" should have encryption enabled

Run it:

infraspec features/s3_bucket.feature

That's it! No code to write, no frameworks to learn. InfraSpec handles the rest.

✨ Features

• 🗣️ Plain English syntax - Write tests that read like documentation using Gherkin
• 👥 Team-friendly - Non-technical stakeholders can read, review, and contribute
• 🚀 Zero boilerplate - Works with your existing Terraform configurations out of the box
• 📚 Rich assertion library - Hundreds of pre-built assertions for AWS resources
• ⚡ Fast feedback - Catch infrastructure issues before they reach production
• 🔄 CI/CD ready - Integrates seamlessly with your existing pipelines
• 💰 Cost effective - Use Virtual Cloud to eliminate AWS testing costs
• 🧪 Flexible testing - Test against real AWS or Virtual Cloud emulator

🚀 Installation

Homebrew (macOS/Linux)

brew tap robmorgan/infraspec
brew install infraspec

Go Install

go install github.com/robmorgan/infraspec@latest

Binary Download

Download the latest release for your platform from the releases page.

Verify Installation

infraspec --version

📖 Getting Started

1. Initialize Your Project

Navigate to your Terraform project directory and initialize InfraSpec:

cd my-terraform-project
infraspec init

This creates a features/ directory where your tests will live.

2. Create Your First Test

Generate a test template for the service you want to test:

infraspec new s3_bucket.feature

Or create a test manually in features/s3_bucket.feature:

Feature: S3 Bucket Security
  Scenario: Bucket has encryption enabled
    Given I have a Terraform configuration in "./terraform/s3"
    And I set variable "bucket_name" to "test-bucket" with a random suffix
    When I run Terraform apply
    Then the S3 bucket from output "bucket_name" should exist
    And the S3 bucket from output "bucket_name" should have encryption enabled

3. Run Your Tests

infraspec features/s3_bucket.feature

Or run all tests:

infraspec features/

Optionally use InfraSpec Virtual Cloud for rapid testing with zero cleanup:

infraspec --virtual-cloud features/

→ Learn more about InfraSpec Virtual Cloud

4. Integrate with CI/CD

Add to your GitHub Actions workflow:

- name: Run InfraSpec Tests
  run: |
    infraspec features/

🔍 What Can You Test?

🏗️ Terraform

• ✅ Resource configurations and outputs
• ✅ Security policies and compliance rules
• ✅ Cost optimization validations
• ✅ Multi-environment consistency
• ✅ Variable validation

☁️ AWS Resources

→ See the AWS Compatibility page for the current status

🌐 HTTP/APIs

• ✅ HTTP(S) endpoints and status codes
• ✅ Response headers and bodies
• ✅ Form data and file uploads
• ✅ JSON/XML response validation

📚 Real-World Examples

DynamoDB Table with GSI

Scenario: DynamoDB table with Global Secondary Index
  Given I have a Terraform configuration in "./terraform/dynamodb"
  And I set variable "table_name" to "users-table" with a random suffix
  When I run Terraform apply
  Then the DynamoDB table from output "table_name" should exist
  And the DynamoDB table from output "table_name" should have encryption enabled
  And the DynamoDB table from output "table_name" should have "PAY_PER_REQUEST" billing mode
  And the DynamoDB table from output "table_name" should have 1 global secondary index

RDS Instance Security

Scenario: RDS instance meets security requirements
  Given I have a Terraform configuration in "./terraform/rds"
  And I set variable "db_identifier" to "production-db" with a random suffix
  When I run Terraform apply
  Then the RDS instance from output "db_instance_id" should exist
  And the RDS instance from output "db_instance_id" should not be publicly accessible
  And the RDS instance from output "db_instance_id" should have encryption enabled
  And the RDS instance from output "db_instance_id" should have automated backups enabled

Multi-Environment Validation

Scenario Outline: S3 bucket configuration across environments
  Given I have a Terraform configuration in "./terraform/s3"
  And I set variable "environment" to "<environment>"
  When I run Terraform apply
  Then the S3 bucket from output "bucket_name" should exist
  And the S3 bucket from output "bucket_name" should have the tag "Environment" with value "<environment>"

  Examples:
    | environment |
    | dev         |
    | staging     |
    | production  |

🆚 InfraSpec vs. Alternatives

Feature	InfraSpec	Terratest	Terraform Testing	Conftest
Language	Plain English (Gherkin)	Go	HCL	Rego
Learning Curve	Low	High	Medium	Medium
AWS Integration	Native	Manual	Limited	Policy-based
Non-technical Friendly	✅ Yes	❌ No	⚠️ Partial	❌ No
Live Resource Testing	✅ Yes	✅ Yes	❌ No	❌ No
Pre-built Assertions	✅ Hundreds	❌ None	⚠️ Some	❌ None

🎯 Roadmap

We're actively expanding InfraSpec's capabilities. For more information see the compatibility page.

💡 Editor Support

VS Code

Install the Cucumber (Gherkin) Full Support extension for:

• Syntax highlighting
• Auto-completion
• Step definition navigation

IntelliJ IDEA / PyCharm

Enable the built-in Gherkin plugin for full IDE support.

🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes InfraSpec better.

Ways to Contribute

• 🐛 Report bugs
• 💡 Request features
• 📝 Improve documentation
• 🔧 Submit pull requests
• ⭐ Star the project to show support

Development Setup

# Clone the repository
git clone https://github.com/robmorgan/infraspec.git
cd infraspec

# Install dependencies
make deps

# Run tests
make test

# Build locally
make build

Note: Our tests use InfraSpec Virtual Cloud, a high-fidelity AWS emulator, to save time and costs during development. The Virtual Cloud API is available as a paid service for production use.

See CONTRIBUTING.md for detailed guidelines.

📞 Community & Support

• 💬 GitHub Discussions - Ask questions and share ideas
• 🐛 Issue Tracker - Report bugs and request features
• 📖 Documentation - Full documentation and guides
• 🐦 Twitter/X - Follow @_rjm_ for updates

📄 License

InfraSpec is open source software licensed under the Apache License 2.0.

---

Made with ❤️ by Rob Morgan and contributors
⭐ Star us on GitHub to support the project!