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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c565d7154d7321b3b6b9452592201b5230bbba63e30a3603e233f9ebd8f5bc9d
-  data.tar.gz: d9a59fe476ba65bd885da0386e3696e9e41daaf71b98d48f4c89a6dbcc7d56ba
+  metadata.gz: 71e9d6c1dcc91011ceaaf7e50cb2f449453ed10157afa51675e644404df114cb
+  data.tar.gz: c7efffc268030aedb282fb8e72dfb2d7d1ee9ae97c8fe0896f08e3817aeb8a42
 SHA512:
-  metadata.gz: 05d52e392f0a08c5d4e1cd1eefccba1d11782f628c88426815e1ae5665e1aaf024f8119d2be4de264487670471bdb52bc8636e52be9c61249491180b433ad8ca
-  data.tar.gz: 7d5f89bd7ca96606e89104b4541f9ccde0b89619b0bbcedad2c95b63e5b82ac87ae31a05eaf2dafaf758131970d34be8576123a0f791bd3aff8921b0e13d5338
+  metadata.gz: a57bb3067903397d0378278b20a4e1f91ff1e5fde1576a8e156221279d33d64a316d3704b6f5cbad2317e000e80a12ec4c152f7b7fcda731f1956516c7363f62
+  data.tar.gz: '094cc08b00bf0209439809d707636a1a4bcf112865bc6f6ce9a90b0d558719e11fcb18ad318bf4f81a08fed2938ce71057463cdf44a4f5abfc645c6ebbd7bd9a'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-terraform (0.1.0.pre.48)
+    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/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Terraform
-    VERSION = '0.1.0.pre.48'
+    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.48
+  version: 0.1.0.pre.49
 platform: ruby
 authors:
 - InfraBlocks Maintainers
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-09-30 00:00:00.000000000 Z
+date: 2022-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: confidante