Adding experimental status and example usage for ExpectKnownValue, …

…`ExpectKnownOutputValue`, and `ExpectKnownOutputValueAtPath` plan and state checks (#276)

* Adding StateCheck interface (#266)

  * Configuring when state checks are executed.
  * Testing that state checks are executed.

* Adding validation to ensure state checks are only defined for config (apply) tests (#266)

* Adding ExpectKnownValue state check (#266)

* Adding ExpectKnownOutputValue state check (#266)

* Adding ExpectKnownOutputValueAtPath state check (#266)

* Modifying ExpectKnown<Value|OutputValue|OutputValueAtPath> to allow for checking of null values (#266)

* Adding ExpectSensitiveValue state check (#266)

* Adding documentation for state checks and null known value check type (#266)

* Adding to the documentation for the custom known value check (#266)

* Adding changelog entries (#266)

* Refactoring to use updated known value check types (#266)

* Correcting documentation for revised naming of known value check types (#266)

* Renaming nul known value check (#266)

* Fixing tests (#266)

* Adding address and path to state check errors (#266)

* Fixing navigation (#266)

* Adding ExpectNoValueExists check to replace TestCheckNoResourceAttr

* Adding ExpectMatchingValues check to replace TestCheckResourceAttrPair

* Adding BoolPointerExact to illustrate a possible replacement for TestCheckResourceAttrPtr

* Adding ExpectValueExists state check to replace TestCheckResourceAttrSet

* Fixing bool pointer exact error message

* Adding ExpectContains state check to replace TestCheckTypeSetElemAttrPair

* Removing unneeded bool pointer exact check value type

* Adding docs for new built-in state checks

* Adding deprecations

* Fixing doc

* Adding changelog entries

* Fixing changelog entries

* Linting

* Modifying ExpectKnown<Value|OutputValue|OutputValueAtPath> to handle null checking (#266)

* Deprecating ExpectNullOutputValue and ExpectNullOutputValueAtPath plan checks (#266)

* Updating docs

* Adding further Go docs to illustrate migration from built-in TestCheckFunc(s), and include example usage of state checks

* Adding return statements (#266)

* Adding change log entry for deprecation of `ExpectNullOutputValue` and `ExpectNullOutputValueAtPath` plan checks (#266)

* Modifying return value of nullExact.String() (#266)

* Renaming variable (#266)

* Adding comment for Terraform v1.4.6 (#266)

* Adding further tests for null exact known value type check (#266)

* Linting (#266)

* Moving code examples to Go doc example files

* Adding deprecation note to website docs for ExpectNullOutputValue and ExpectNullOutputValueAtPath

* Adding return statements

* Renaming variables

* Modify wording of error message

* Remove unneeded file

* Renaming BoolExact to Bool, and NullExact to Null (#266)

* Removing ConfigStateChecks type (#266)

* Move execution of ConfigStateChecks (#266)

* Replacing usage of ConfigStateChecks, BoolExact and NullExact types

* Removing ExpectValueExists state check

  * Adding known value not null check type

* Adding Terraform version check

* Removing ExpectContains state check

* Removing ExpectMatchingValues state check

* Updating docs

* Apply suggestions from code review

Co-authored-by: Brian Flad <[email protected]>

* Removing ExpectNoValueExists

* Adding knownvalue.StringRegularExpression

* Adding `CheckStateFunc` type and test for illustrating replacement of TestCheckResourceAttrPtr

* Updating docs regarding usage of preferring direct testing of resource attributes rather than using output values

* Modify docs to highlight caveats of using ExpectKnownOutputValueAtPath plan check with versions of Terraform <1.3.0

* Fixing test

* Updating docs

* Removing deprecation of built-in TestCheckFunc implementations

* Updating tests

* Remove CheckStateFunc type

* Updating docs

* Adding changelog

* Fixing links

* Adding changelog entries

* Removing nolint directives

* Updating docs and renaming following code review

* Updating docs following code review

---------

Co-authored-by: Brian Flad <[email protected]>
Co-authored-by: Austin Valle <[email protected]>

.changes/unreleased/NOTES-20240122-082628.yaml

@@ -1,7 +1,7 @@
 kind: NOTES
 body: 'plancheck: Deprecated `ExpectNullOutputValue` and `ExpectNullOutputValueAtPath`.
   Use `ExpectKnownOutputValue` and `ExpectKnownOutputValueAtPath` with 
-  `knownvalue.NullExact` instead'
+  `knownvalue.Null` instead'
 time: 2024-01-22T08:26:28.053303Z
 custom:
   Issue: "275"

.changes/unreleased/NOTES-20240229-112244.yaml

@@ -0,0 +1,6 @@
+kind: NOTES
+body: 'plancheck: `ExpectKnownValue`, `ExpectKnownOutputValue` and `ExpectKnownOutputValueAtPath`
+  plan checks are considered experimental and may be altered or removed in a subsequent release'
+time: 2024-02-29T11:22:44.292647Z
+custom:
+  Issue: "276"

.changes/unreleased/NOTES-20240229-112333.yaml

@@ -0,0 +1,6 @@
+kind: NOTES
+body: 'statecheck: `ExpectKnownValue`, `ExpectKnownOutputValue` and `ExpectKnownOutputValueAtPath`
+  state checks are considered experimental and may be altered or removed in a subsequent release'
+time: 2024-02-29T11:23:33.77075Z
+custom:
+  Issue: "276"

.changes/unreleased/NOTES-20240229-112401.yaml

@@ -0,0 +1,6 @@
+kind: NOTES
+body: 'knownvalue: The `knownvalue` package is considered experimental and may
+  be altered or removed in a subsequent release'
+time: 2024-02-29T11:24:01.600093Z
+custom:
+  Issue: "276"