Comments to clarify TestCheckResourceAttrSet()

[justinTM]

closes #885

[bflad]

Hi @justinTM 👋 Thank you for submitting this.

It's technically possible to inspect any type of state value using the various TestCheck* and TestMatch functions; it requires knowing Terraform 0.11 and older syntax in certain cases. Those cases are documented at the bottom of the Builtin Check Functions section of the acceptance testing documentation, however if only seeing the Go documentation, it can certainly be hard to know that, which we probably should adjust for future travelers. 😅

I believe in this case, we'd probably want to include the special cases to all the TestCheck and TestMatch function Go documentation. Copy-pasting comments like this is certainly less than ideal, but preferable over putting a very specific documentation URL which can change over time and is hard to check/maintain.

Appending something like the following Go documentation to the following functions should help:

• TestCheckResourceAttrSet
• TestCheckResourceAttr
• TestCheckNoResourceAttr
• TestMatchResourceAttr
• TestCheckResourceAttrPtr
• TestCheckResourceAttrPair

// ... existing Go documentation ...
//
// Use the following special key syntax to inspect list and map values
// of an attribute:
//   .{NUMBER}: List value at index, e.g. .0 to inspect the first element
//   .{KEY}: Map value at key, e.g. .example to inspect the example key value
//   .#: Number of elements in list or set
//   .%: Number of elements in map

Thanks again for raising this and please reach out with any questions.

[bflad]

Thinking about this more, one complication here is that indeed checking the list/set/map attribute itself, not one of the special sub-keys, will likely not be represented in the flatmap state. I'm wondering if it might be best to mention both things in that case by having a statement such as "Collection attributes can only be inspected by the special key syntax, not the attribute key itself."

[bflad]

Hi again, @justinTM 👋 Since I haven't heard back from you for awhile, I'm going to close this. I'll submit the above suggestions separately so the Go documentation is updated appropriately. Thanks again for raising this.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.