Documentation
¶
Overview ¶
Package snapshot provides JSON snapshot testing for Terraform plans and other deterministic JSON payloads, plus a small extraction toolkit for the IAM-heavy use cases that motivate it.
Three building blocks:
- JSONStrict — byte-for-byte comparison against a snapshot file. Use when key order is semantically meaningful.
- JSONStructural — normalizes both sides (recursively sorts keys and strips insignificant whitespace) before comparing. Use for IAM policies, Terraform plan JSON, and anywhere key order is arbitrary.
- ExtractIAMPolicies / ExtractResourceAttribute — pull JSON payloads out of `terraform show -json plan.out` output ready to feed into JSONStructural.
The UPDATE_SNAPSHOTS=1 protocol ¶
When LIBTFTEST_UPDATE_SNAPSHOTS=1 is set in the environment, missing or mismatched snapshots are overwritten with the actual payload and the test passes (with a tb.Logf record). This matches the Jest snapshot workflow and the `go-cmp` "regenerate goldens" pattern. Always commit the regenerated snapshots — they ARE the test.
Determinism guarantees ¶
All helpers are pure functions of their byte inputs. None of them make network calls. ExtractIAMPolicies in particular renders AWS managed policy attachments as the canonical ARN string rather than fetching the live document — the ARN is effectively an enum AWS owns, and fetching would make the helper non-deterministic and network-dependent. The same applies to customer-managed policies attached by ARN: the snapshot captures the attachment, not the policy document, which is a separate snapshot if the module owns the document.
Index ¶
- func ExtractIAMPolicies(planJSON []byte) (map[string][]byte, error)
- func ExtractResourceAttribute(planJSON []byte, resourceAddress, attributePath string) ([]byte, error)
- func JSONStrict(tb testing.TB, actual []byte, path string)
- func JSONStructural(tb testing.TB, actual []byte, path string)
- func NormalizeJSON(raw []byte) ([]byte, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractIAMPolicies ¶
ExtractIAMPolicies walks `planned_values.root_module.resources` in a `terraform show -json plan.out` payload and returns one entry per IAM-policy-bearing resource keyed by the resource address plus a suffix that distinguishes the policy slot:
- `<addr>.assume_role` — aws_iam_role.assume_role_policy
- `<addr>.inline:<name>` — aws_iam_role_policy (inline policy)
- `<addr>.managed:<arn>` — aws_iam_role_policy_attachment
- `<addr>.policy` — aws_iam_policy.policy
Inline policies and assume-role policies render as full JSON documents. Managed-policy attachments and customer-managed-policy attachments render as the canonical ARN string — they're effectively an enum (AWS owns them; we don't fetch live documents because that would make the helper network-dependent and non-deterministic).
The returned map's iteration order is undefined; callers that snapshot a single key in isolation should use the returned bytes directly, and callers that aggregate must sort the keys explicitly.
func ExtractResourceAttribute ¶
func ExtractResourceAttribute(planJSON []byte, resourceAddress, attributePath string) ([]byte, error)
ExtractResourceAttribute returns the JSON bytes at attributePath under `planned_values.root_module.resources[?address==resourceAddress].values`. attributePath uses dot notation (e.g. `policy`, `tags.Owner`).
Returns an error if the resource address isn't found, the attribute path doesn't resolve, or the JSON is malformed.
func JSONStrict ¶
JSONStrict compares actual JSON bytes against the snapshot at path byte-for-byte. Failures call tb.Errorf with a short diff hint. When LIBTFTEST_UPDATE_SNAPSHOTS=1, a missing or mismatched snapshot is overwritten with actual and the test passes.
func JSONStructural ¶
JSONStructural normalizes actual and the snapshot (recursively sorts object keys and strips insignificant whitespace) before comparing. Use for IAM policies, plan JSON, and any payload whose key order is not semantically meaningful. When LIBTFTEST_UPDATE_SNAPSHOTS=1, a missing or mismatched snapshot is overwritten with the normalized actual and the test passes.
func NormalizeJSON ¶
NormalizeJSON parses raw and re-emits it with object keys sorted recursively and insignificant whitespace stripped. Exposed so callers can produce a normalized form for direct comparison without the snapshot-file plumbing.
Types ¶
This section is empty.
Source Files