Publicly expose terraform.parsePlanJson function for ease of testing Terraform plans

[mdb]

👋 Thanks for your work on terratest! I'd love to see terraform.parsePlanJson be publicly exported (perhaps as a terraform.ParsePlanJSON function).

Context and use case

terratest v0.30.15 introduced the ability to write terratest tests against Terraform plan output, which is great! However, terratest assumes the terraform.PlanStruct has been generated from terratest-orchestrated terraform CLI commands, such as terraform.InitAndPlanAndShowWithStruct. terratest provides no mechanism or API for producing a terraform.PlanStruct from raw Terraform plan JSON, as might be beneficial when using terratest to programmatically analyze and validate a Terraform plan produced by a separate, upstream process (such as a preceding CI/CD job step) that is not orchestrated via terratest.

For example, consider the following contrived GitHub Actions workflow, which could use terratest's terraform.ParsePlanJSON in its Terratest test plan.json step to programmatically analyze plan output produced by the preceding Terraform plan step and gate the Terraform apply step accordingly, without requiring that terratest orchestrate the invocation of the terraform CLI:

jobs:
  terraform:
    name: Terraform
    runs-on: ubuntu-latest
    steps:
    ...
    - name: Terraform plan
      run: terraform plan -out=plan.out
    - name: Generate Terraform plan.json
      run: terraform show -json plan.out > plan.json
    - name: Terratest test plan.json
      run: go test
    - name: Terratest apply
      run: terraform apply plan.out

Via a terraform.ParsePlanJSON function, terratest's testing of the plan.json is decoupled from the actual invocation of the terraform CLI that produced the plan.json. I think this is especially useful in contexts where teams have non-terratest-orchestrated CI/CD logic surrounding the invocation of the terraform CLI, but where those teams would also like to leverage terratest to evaluate the plan results.

Additionally, this also enables the use of terratest Terraform plan testing in contexts where the terraform executable is not installed, as may be the case when separate, distinct OCI container images are responsible for invoking terraform and terratest tests.

[denis256]

Exposed terraform.ParsePlanJSON() function as part of https://github.com/gruntwork-io/terratest/releases/tag/v0.43.8