helper/resource: Additional Go documentation for TestCheck and TestMatch functions #911
Conversation
…tch functions Reference: #885
| // The key parameter is an attribute path in Terraform CLI 0.11 and earlier | ||
| // "flatmap" syntax. Keys start with the attribute name of a top-level |
There was a problem hiding this comment.
Does it make sense to make references to what is now an "ancient" version of Terraform? Do we have a public doc explaining this "flatmap" syntax?
There was a problem hiding this comment.
I would love to reference something, but I'm not sure if there's any terraform.io documentation left on it. 🙁 I'll do some digging, but I'm doubtful. In place of finding that, I'm wondering if Go testable examples might help at least slightly here.
There was a problem hiding this comment.
The closest thing I can find is: https://www.terraform.io/language/configuration-0-11/interpolation#attributes-of-other-resources, but I think linking to that would honestly be more confusing than anything. The flatmap bits were a detail of the previous state storage mechanism. I've uploaded some TestCheckFunc examples instead.
helper/resource/testing.go
Outdated
| // values of a list or map 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 |
There was a problem hiding this comment.
It would feel more "complete" if, as part of the flow of what you are explaining here, and the 2 special keys you just explained, there was an example that built on the above examples.
Something that would show that for
data "myprovider_thing" "example" {
attributeName {
k1 = "v1"
}
}
they could use this function like:
TestCheckResourceAttrSet("data.myprovider_thing.example", "attributeName.k1")
Does it make sense?
There was a problem hiding this comment.
Yeah totally -- I meant to implement Go testable examples for these as part of this update.
It's going to be a little awkward though, because its only recommended to implement these for Computed values, but I'll essentially have to show the configuration equivalent so it makes more sense looking at it.
There was a problem hiding this comment.
I've uploaded some TestCheckFunc examples.
| // exists in state for the given name/key combination. It is useful when | ||
| // testing that computed values were set, when it is not possible to | ||
| // know ahead of time what the values will be. | ||
| // TestCheckResourceAttrSet ensures any value exists in the state for the |
There was a problem hiding this comment.
It took me reading this twice to realise that the Set suffix here means "that it is set" and not that it usable with TypeSet.
🤦♀️
Nitpick: Probably too late to change it to IsSet suffix?
There was a problem hiding this comment.
Yeah, that's certainly a good naming callout, although that ship sailed years ago. 🚢 I'd also vote for TestCheckResourceAttrAnyValue or something (and alias TestCheckNoResourceAttr to TestCheckResourceAttrNoValue) if we were to change it/them. It is not worth the developer burden at this point though, in my opinion.
There was a problem hiding this comment.
Of course. Naming, especially that lasts the test of time, is hard.
helper/resource/testing.go
Outdated
| // for sets. | ||
| // - .{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 |
There was a problem hiding this comment.
As above, an "end to end" example would put a nice bow here.
There was a problem hiding this comment.
I've uploaded some TestCheckFunc examples.
helper/resource/testing.go
Outdated
| // values of a list or map 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 |
There was a problem hiding this comment.
About the example, as above.
There was a problem hiding this comment.
I've uploaded some TestCheckFunc examples.
helper/resource/testing.go
Outdated
| // for sets. | ||
| // - .{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 |
There was a problem hiding this comment.
I've uploaded some TestCheckFunc examples.
helper/resource/testing.go
Outdated
| // for sets. | ||
| // - .{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 |
There was a problem hiding this comment.
I've uploaded some TestCheckFunc examples.
|
I think you might need to tweak the formatting a bit, as the godoc renderer is getting a bit confused in some points. |
|
But godoc formatting aside, this is excellent. |
|
@detro THANK YOU! I always forget the correct list formatting bits in Go doc (the current thing today is to just treat them as a code block). I've pushed up the changes to that and it looks much, much better.
Excited to see the proposal golang/go#51082 land yesterday, which will definitely make this documentation easier to write in the future. 🎉 Aside: I also forget about the title formatting, which would probably help with some of the longer documentation bits, but we can always follow up with those at any time. |
Reference: #911 Additional glow up for the `TypeSet` functions, similar to the others.
|
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. |
Closes #885