rspec-terraform 0.1.0.pre.47 → 0.1.0.pre.49

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81533be8b2db5deed030c7d321cf443d1703b7c8e71d7379c70463fab9a9d3f6
-  data.tar.gz: 77b1e6c0b70fc4fd4a258f0a3d6db4c8aa1e404e6059c2eed81ef0163b59509e
+  metadata.gz: 71e9d6c1dcc91011ceaaf7e50cb2f449453ed10157afa51675e644404df114cb
+  data.tar.gz: c7efffc268030aedb282fb8e72dfb2d7d1ee9ae97c8fe0896f08e3817aeb8a42
 SHA512:
-  metadata.gz: c53f5bfe578e18b842e0d509c582fca0c06cb106c10d8fcde12c20361fd2c53b546e3b62dd60109af3bbcb71116c39d4ffcac29703cfa6399b3187da26ab5b58
-  data.tar.gz: 294f50f7e73613ade97534b6706d5df40c6194d50746509826c92f7692484f7cab267e34741257bada91fb1ff92e5e3b5fc7699a506cd6c1870d200f6ba719fb
+  metadata.gz: a57bb3067903397d0378278b20a4e1f91ff1e5fde1576a8e156221279d33d64a316d3704b6f5cbad2317e000e80a12ec4c152f7b7fcda731f1956516c7363f62
+  data.tar.gz: '094cc08b00bf0209439809d707636a1a4bcf112865bc6f6ce9a90b0d558719e11fcb18ad318bf4f81a08fed2938ce71057463cdf44a4f5abfc645c6ebbd7bd9a'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-terraform (0.1.0.pre.47)
+    rspec-terraform (0.1.0.pre.49)
       confidante (>= 0.27)
       rspec (>= 3.0)
       ruby-terraform (= 1.7.0.pre.17)

data/README.md

@@ -1,6 +1,11 @@
 # RSpec::Terraform
 
-RSpec support for testing Terraform configurations.
+An RSpec extension for verifying Terraform configurations, with support for:
+
+* unit testing;
+* integration testing;
+* end-to-end testing; and
+* change auditing.
 
 ## Installation
 
@@ -20,19 +25,167 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write docs.
+To use RSpec::Terraform, require it in your `spec_helper.rb` file:
+
+```ruby
+require 'rspec/terraform'
+```
+
+When required, RSpec::Terraform automatically configures itself against 
+RSpec by:
+
+* adding helper methods to interact with Terraform;
+* adding matchers to verify Terraform plans; and
+* adding settings to control RSpec::Terraform's behaviour.
+
+The sections below provide further details on each of these additions.
+
+### Helper methods
+
+RSpec::Terraform adds helper methods to the RSpec DSL for planning, applying,
+and destroying Terraform configurations, as well as accessing variables to and
+outputs from Terraform configurations.
+
+Each helper method takes a hash of parameters used to identify the configuration
+against which to act and to provide as options to the Terraform command being
+executed. Additionally, RSpec::Terraform includes a flexible approach to
+resolving these parameters allowing them to be sourced from a variety of
+locations. See the [Configuration Providers](#configuration-providers) section
+for more details.
+
+When executing helper methods, RSpec::Terraform provides two execution modes,
+`:in_place` and `:isolated`. By default, RSpec::Terraform works against a
+Terraform configuration _in place_, i.e., it executes commands against the
+Terraform configuration directly, in the location specified. RSpec::Terraform
+can also operate in an _isolated_ manner, wherein it initialises the
+configuration into an isolated directory before executing commands. See the
+[Execution Mode](#execution-mode) section for more details.
+
+#### `plan`
+
+The `plan` helper produces a Terraform plan for a configuration, reads it
+into a Ruby representation and returns it.
+
+`plan` requires a `:configuration_directory` parameter, representing the path
+to the configuration to plan and is typically invoked in a `before(:context)`
+hook, with the resulting plan stored for use in expectations:
+
+```ruby
+before(:context) do
+  @plan = plan(
+    configuration_directory: 'path/to/configuration/directory'
+  )
+end
+```
+
+If the configuration has input variables, a `:vars` parameter can be provided
+as a hash:
+
+```ruby
+before(:context) do
+  @plan = plan(
+    configuration_directory: 'path/to/configuration/directory',
+    vars: {
+      region: 'uk',
+      zones: ['uk-a', 'uk-b'],
+      tags: {
+        name: 'important-thing',
+        role: 'persistence'
+      }
+    }
+  )
+end
+```
+
+or within a block:
+
+```ruby
+before(:context) do
+  @plan = plan(
+    configuration_directory: 'path/to/configuration/directory'
+  ) do |vars|
+    vars.region = 'uk'
+    vars.zones = ['uk-a', 'uk-b']
+    vars.tags = {
+      name: 'important-thing',
+      role: 'persistence'
+    }
+  end
+end
+```
+
+`plan` accepts an optional `:state_file` parameter with the path to where the
+current state file for the configuration is located, useful when checking the
+incremental change that applying the configuration would have after a previous
+apply.
+
+Internally, `plan`:
+* calls `terraform init` to initialise the configuration directory;
+* calls `terraform plan` to produce a plan file;
+* calls `terraform show` to read the contents of the plan file into a Ruby
+  representation; and
+* deletes the plan file.
+
+Any additional parameters passed to `plan` are passed on to the underlying
+Terraform invocations.
+
+#### `apply`
+
+#### `destroy`
+
+#### `output`
+
+#### `var`
+
+### Plan Matchers
+
+### Settings
+
+#### Binary Location
+
+#### Logging and Standard Streams
+
+#### Execution Mode
+
+The benefit of isolated execution is that nothing is carried over between test
+runs and providers and modules are fetched into a clean configuration directory
+every time. The downside is additional test run time.
+
+#### Configuration Providers
+
+### Frequently Asked Questions
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment.
+To install dependencies and run the build, run the pre-commit build:
+
+```shell
+./go
+```
+
+This runs all unit tests and other checks including coverage and code linting /
+formatting.
+
+To run only the unit tests, including coverage:
+
+```shell
+./go test:unit
+```
+
+To attempt to fix any code linting / formatting issues:
+
+```shell
+./go library:fix
+```
+
+To check for code linting / formatting issues without fixing:
+
+```shell
+./go library:check
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push
-git commits and tags, and push the `.gem` file to
-[rubygems.org](https://rubygems.org).
+You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
 
 ### Managing CircleCI keys
 

data/lib/rspec/terraform/helpers/actions/apply.rb

@@ -12,11 +12,33 @@ module RSpec
           include CommandInstantiation
 
           def apply(parameters)
-            apply_command.execute(apply_parameters(parameters))
+            parameters = apply_parameters(parameters)
+
+            log_apply_starting(parameters)
+            log_apply_using_parameters(parameters)
+
+            apply_command.execute(parameters)
+
+            log_apply_complete
           end
 
           private
 
+          def log_apply_starting(parameters)
+            logger&.info(
+              'Applying for configuration in directory: ' \
+              "'#{parameters[:chdir]}'..."
+            )
+          end
+
+          def log_apply_using_parameters(parameters)
+            logger&.debug("Applying using parameters: #{parameters}...")
+          end
+
+          def log_apply_complete
+            logger&.info('Apply complete.')
+          end
+
           def apply_command
             instantiate_command(RubyTerraform::Commands::Apply)
           end
@@ -28,16 +50,23 @@ module RSpec
           end
 
           def with_apply_standard_parameters(parameters)
-            parameters.merge(
-              chdir: parameters[:configuration_directory],
-              input: false,
-              auto_approve: true
-            )
+            configuration_directory = parameters[:configuration_directory]
+
+            parameters
+              .except(:configuration_directory)
+              .merge(
+                chdir: configuration_directory,
+                input: false,
+                auto_approve: true
+              )
           end
 
           def with_apply_state_file_parameters(parameters)
-            if parameters[:state_file]
-              return parameters.merge(state: parameters[:state_file])
+            state_file = parameters[:state_file]
+            if state_file
+              return parameters
+                       .except(:state_file)
+                       .merge(state: state_file)
             end
 
             parameters

data/lib/rspec/terraform/helpers/actions/clean.rb

@@ -8,8 +8,27 @@ module RSpec
           def clean(parameters)
             return unless execution_mode == :isolated
 
-            FileUtils.rm_rf(parameters[:configuration_directory])
-            FileUtils.mkdir_p(parameters[:configuration_directory])
+            configuration_directory = parameters[:configuration_directory]
+
+            log_clean_starting(configuration_directory)
+
+            FileUtils.rm_rf(configuration_directory)
+            FileUtils.mkdir_p(configuration_directory)
+
+            log_clean_complete
+          end
+
+          private
+
+          def log_clean_starting(configuration_directory)
+            logger&.info(
+              'Cleaning configuration directory: ' \
+              "'#{configuration_directory}'..."
+            )
+          end
+
+          def log_clean_complete
+            logger&.info('Clean complete.')
           end
         end
       end

data/lib/rspec/terraform/helpers/actions/destroy.rb

@@ -12,11 +12,33 @@ module RSpec
           include CommandInstantiation
 
           def destroy(parameters)
-            destroy_command.execute(destroy_parameters(parameters))
+            parameters = destroy_parameters(parameters)
+
+            log_destroy_starting(parameters)
+            log_destroy_using_parameters(parameters)
+
+            destroy_command.execute(parameters)
+
+            log_destroy_complete
           end
 
           private
 
+          def log_destroy_starting(parameters)
+            logger&.info(
+              'Destroying for configuration in directory: ' \
+              "'#{parameters[:chdir]}'..."
+            )
+          end
+
+          def log_destroy_using_parameters(parameters)
+            logger&.debug("Destroying using parameters: #{parameters}...")
+          end
+
+          def log_destroy_complete
+            logger&.info('Destroy complete.')
+          end
+
           def destroy_command
             instantiate_command(RubyTerraform::Commands::Destroy)
           end
@@ -28,16 +50,23 @@ module RSpec
           end
 
           def with_destroy_standard_parameters(parameters)
-            parameters.merge(
-              chdir: parameters[:configuration_directory],
-              input: false,
-              auto_approve: true
-            )
+            configuration_directory = parameters[:configuration_directory]
+
+            parameters
+              .except(:configuration_directory)
+              .merge(
+                chdir: configuration_directory,
+                input: false,
+                auto_approve: true
+              )
           end
 
           def with_destroy_state_file_parameters(parameters)
-            if parameters[:state_file]
-              return parameters.merge(state: parameters[:state_file])
+            state_file = parameters[:state_file]
+            if state_file
+              return parameters
+                       .except(:state_file)
+                       .merge(state: state_file)
             end
 
             parameters

data/lib/rspec/terraform/helpers/actions/execute_if_required.rb

@@ -5,12 +5,35 @@ module RSpec
     module Helpers
       module Actions
         module ExecuteIfRequired
-          def execute_if_required(parameters, &block)
+          def execute_if_required(name, parameters, &block)
+            log_execute_if_required_starting(name)
+
+            if should_execute(parameters)
+              log_execute_if_required_continuing
+              block.call
+            else
+              log_execute_if_required_skipping
+            end
+          end
+
+          private
+
+          def should_execute(parameters)
             only_if = parameters[:only_if]
             only_if_args = only_if ? [parameters].slice(0, only_if.arity) : []
-            should_execute = only_if ? only_if.call(*only_if_args) : true
+            only_if ? only_if.call(*only_if_args) : true
+          end
+
+          def log_execute_if_required_starting(name)
+            logger&.info("Checking if execution of #{name} required...")
+          end
+
+          def log_execute_if_required_continuing
+            logger&.info('Execution required. Continuing...')
+          end
 
-            block.call if should_execute
+          def log_execute_if_required_skipping
+            logger&.info('Execution not required. Skipping...')
           end
         end
       end

data/lib/rspec/terraform/helpers/actions/init.rb

@@ -12,11 +12,33 @@ module RSpec
           include CommandInstantiation
 
           def init(parameters)
-            init_command.execute(init_parameters(parameters))
+            parameters = init_parameters(parameters)
+
+            log_init_starting(parameters)
+            log_init_using_parameters(parameters)
+
+            init_command.execute(parameters)
+
+            log_init_complete
           end
 
           private
 
+          def log_init_starting(parameters)
+            logger&.info(
+              'Initing for configuration in directory: ' \
+              "'#{parameters[:chdir]}'..."
+            )
+          end
+
+          def log_init_using_parameters(parameters)
+            logger&.debug("Initing using parameters: #{parameters}...")
+          end
+
+          def log_init_complete
+            logger&.info('Init complete.')
+          end
+
           def init_command
             instantiate_command(RubyTerraform::Commands::Init)
           end
@@ -28,17 +50,22 @@ module RSpec
           end
 
           def with_init_standard_parameters(parameters)
-            parameters.merge(
-              chdir: parameters[:configuration_directory],
-              input: false
-            )
+            configuration_directory = parameters[:configuration_directory]
+
+            parameters
+              .except(:configuration_directory)
+              .merge(
+                chdir: configuration_directory,
+                input: false
+              )
           end
 
           def with_init_execution_mode_parameters(parameters)
+            source_directory = parameters[:source_directory]
+            parameters = parameters.except(:source_directory)
+
             if execution_mode == :isolated
-              return parameters.merge(
-                from_module: parameters[:source_directory]
-              )
+              return parameters.merge(from_module: source_directory)
             end
 
             parameters

data/lib/rspec/terraform/helpers/actions/output.rb

@@ -14,13 +14,36 @@ module RSpec
 
           def output(parameters)
             stdout = StringIO.new
+            parameters = output_parameters(parameters)
+
+            log_output_starting(parameters)
+            log_output_using_parameters(parameters)
+
             output_command(stdout: stdout)
-              .execute(output_parameters(parameters))
+              .execute(parameters)
+
+            log_output_complete
+
             stdout.string
           end
 
           private
 
+          def log_output_starting(parameters)
+            logger&.info(
+              'Outputting for configuration in directory: ' \
+              "'#{parameters[:chdir]}'..."
+            )
+          end
+
+          def log_output_using_parameters(parameters)
+            logger&.debug("Outputting using parameters: #{parameters}...")
+          end
+
+          def log_output_complete
+            logger&.info('Output complete.')
+          end
+
           def output_command(opts = {})
             instantiate_command(RubyTerraform::Commands::Output, opts)
           end
@@ -32,14 +55,21 @@ module RSpec
           end
 
           def with_output_standard_parameters(parameters)
-            parameters.merge(
-              chdir: parameters[:configuration_directory]
-            )
+            configuration_directory = parameters[:configuration_directory]
+
+            parameters
+              .except(:configuration_directory)
+              .merge(
+                chdir: configuration_directory
+              )
           end
 
           def with_output_state_file_parameters(parameters)
-            if parameters[:state_file]
-              return parameters.merge(state: parameters[:state_file])
+            state_file = parameters[:state_file]
+            if state_file
+              return parameters
+                       .except(:state_file)
+                       .merge(state: state_file)
             end
 
             parameters

data/lib/rspec/terraform/helpers/actions/plan.rb

@@ -13,13 +13,35 @@ module RSpec
           include CommandInstantiation
 
           def plan(parameters)
-            plan_parameters = plan_parameters(parameters)
-            plan_command.execute(plan_parameters)
-            plan_parameters[:out]
+            parameters = plan_parameters(parameters)
+
+            log_plan_starting(parameters)
+            log_plan_using_parameters(parameters)
+
+            plan_command.execute(parameters)
+
+            log_plan_complete
+
+            parameters[:out]
           end
 
           private
 
+          def log_plan_starting(parameters)
+            logger&.info(
+              'Planning for configuration in directory: ' \
+              "'#{parameters[:chdir]}'..."
+            )
+          end
+
+          def log_plan_using_parameters(parameters)
+            logger&.debug("Planning using parameters: #{parameters}...")
+          end
+
+          def log_plan_complete
+            logger&.info('Plan complete.')
+          end
+
           def plan_command
             instantiate_command(RubyTerraform::Commands::Plan)
           end
@@ -31,17 +53,32 @@ module RSpec
           end
 
           def with_plan_standard_parameters(parameters)
-            parameters.merge(
-              chdir: parameters[:configuration_directory],
-              out: parameters[:plan_file_name] ||
-                "#{SecureRandom.hex[0, 10]}.tfplan",
-              input: false
-            )
+            configuration_directory = parameters[:configuration_directory]
+            plan_file_name = resolve_plan_file_name(parameters)
+
+            parameters
+              .except(:configuration_directory, :plan_file_name)
+              .merge(
+                chdir: configuration_directory,
+                out: plan_file_name,
+                input: false
+              )
+          end
+
+          def resolve_plan_file_name(parameters)
+            parameters[:plan_file_name] || random_plan_file_name
+          end
+
+          def random_plan_file_name
+            "#{SecureRandom.hex[0, 10]}.tfplan"
           end
 
           def with_plan_state_file_parameters(parameters)
-            if parameters[:state_file]
-              return parameters.merge(state: parameters[:state_file])
+            state_file = parameters[:state_file]
+            if state_file
+              return parameters
+                       .except(:state_file)
+                       .merge(state: state_file)
             end
 
             parameters

data/lib/rspec/terraform/helpers/actions/remove.rb

@@ -8,9 +8,28 @@ module RSpec
       module Actions
         module Remove
           def remove(parameters, file)
+            configuration_directory = parameters[:configuration_directory]
+
+            log_remove_starting(configuration_directory, file)
+
             FileUtils.rm_f(
-              File.join(parameters[:configuration_directory], file)
+              File.join(configuration_directory, file)
             )
+
+            log_remove_complete
+          end
+
+          private
+
+          def log_remove_starting(configuration_directory, file)
+            logger&.info(
+              "Removing file: '#{file}' in configuration directory: " \
+              "'#{configuration_directory}'..."
+            )
+          end
+
+          def log_remove_complete
+            logger&.info('Remove complete.')
           end
         end
       end

data/lib/rspec/terraform/helpers/actions/show.rb

@@ -13,14 +13,37 @@ module RSpec
           include CommandInstantiation
 
           def show(parameters, plan_file)
+            parameters = show_parameters(parameters, plan_file)
+
+            log_show_starting(parameters, plan_file)
+            log_show_using_parameters(parameters)
+
             stdout = StringIO.new
             show_command(stdout: stdout)
-              .execute(show_parameters(parameters, plan_file))
+              .execute(parameters)
+
+            log_show_complete
+
             stdout.string
           end
 
           private
 
+          def log_show_starting(parameters, plan_file)
+            logger&.info(
+              "Showing file: '#{plan_file}' in configuration directory: " \
+              "'#{parameters[:chdir]}'..."
+            )
+          end
+
+          def log_show_using_parameters(parameters)
+            logger&.debug("Showing using parameters: #{parameters}...")
+          end
+
+          def log_show_complete
+            logger&.info('Show complete.')
+          end
+
           def show_command(opts = {})
             instantiate_command(RubyTerraform::Commands::Show, opts)
           end
@@ -33,11 +56,15 @@ module RSpec
           end
 
           def with_show_standard_parameters(parameters)
-            parameters.merge(
-              chdir: parameters[:configuration_directory],
-              no_color: true,
-              json: true
-            )
+            configuration_directory = parameters[:configuration_directory]
+
+            parameters
+              .except(:configuration_directory)
+              .merge(
+                chdir: configuration_directory,
+                no_color: true,
+                json: true
+              )
           end
 
           def with_show_plan_file_parameters(parameters, plan_file)

data/lib/rspec/terraform/helpers/actions/validate.rb

@@ -6,17 +6,49 @@ module RSpec
       module Actions
         module Validate
           def validate(parameters)
-            missing_parameters =
-              required_parameters(execution_mode)
-                .filter { |parameter| parameters[parameter].nil? }
+            required = required_parameters(execution_mode)
 
-            return if missing_parameters.empty?
+            log_validate_starting(required)
+            log_validate_using_parameters(parameters)
 
-            raise_missing_parameters(missing_parameters)
+            missing = determine_missing(parameters, required)
+
+            handle_result(missing)
           end
 
           private
 
+          def determine_missing(parameters, required)
+            required.filter { |parameter| parameters[parameter].nil? }
+          end
+
+          def handle_result(missing)
+            if missing.empty?
+              log_validate_successful
+            else
+              log_validate_failed(missing)
+              raise_missing_parameters(missing)
+            end
+          end
+
+          def log_validate_starting(required)
+            logger&.info(
+              "Validating required parameters: #{required} present..."
+            )
+          end
+
+          def log_validate_using_parameters(parameters)
+            logger&.debug("Validating parameters: #{parameters}...")
+          end
+
+          def log_validate_successful
+            logger&.info('Validate successful.')
+          end
+
+          def log_validate_failed(missing)
+            logger&.error("Validate failed. Parameters: #{missing} missing.")
+          end
+
           def raise_missing_parameters(parameters)
             parameters = parameters.collect { |parameter| "`:#{parameter}`" }
             if parameters.count == 1

data/lib/rspec/terraform/helpers/apply.rb

@@ -18,7 +18,7 @@ module RSpec
         def execute(overrides = {}, &block)
           parameters = resolve_parameters(overrides, &block)
 
-          execute_if_required(parameters) do
+          execute_if_required(:apply, parameters) do
             validate(parameters)
             clean(parameters)
             init(parameters)

data/lib/rspec/terraform/helpers/destroy.rb

@@ -18,7 +18,7 @@ module RSpec
         def execute(overrides = {}, &block)
           parameters = resolve_parameters(overrides, &block)
 
-          execute_if_required(parameters) do
+          execute_if_required(:destroy, parameters) do
             validate(parameters)
             clean(parameters)
             init(parameters)

data/lib/rspec/terraform/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Terraform
-    VERSION = '0.1.0.pre.47'
+    VERSION = '0.1.0.pre.49'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-terraform
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.47
+  version: 0.1.0.pre.49
 platform: ruby
 authors:
 - InfraBlocks Maintainers
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-09-25 00:00:00.000000000 Z
+date: 2022-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: confidante