Document usage of Capabilities API in YAML REST tests #108702
Conversation
mosche
added
>test
|
Documentation preview: |
|
Pinging @elastic/es-core-infra (Team:Core/Infra) |
| [[capabilities_check]] | ||
| === Require or skip API capabilities | ||
|
|
||
| As opposed to <<cluster_features,cluster features>>, which are aimed at doing fast checks internally, |
There was a problem hiding this comment.
'... aimed at performing checks internal to Elasticsearch,' I think
|
|
||
| Note: If planning to `skip` on capabilities, keep in mind this might lead to unexpected results in _mixed cluster_ | ||
| tests. A test is only skipped if all nodes support the requested capabilities, in _mixed clusters_ this might not be | ||
| the case: you might randomly hit a node that actually supports what you intended to skip on. |
There was a problem hiding this comment.
I think this might need a bit more explanation - 'you might randomly hit a node that actually supports what you intended to skip on', what is the effect of this? Why does this matter when the capabilities check is across the whole cluster?
There was a problem hiding this comment.
Fair point, this is a tricky one... wdyt about the updated version:
Note: If planning to `skip` on capabilities, keep in mind this might lead to unexpected results in _mixed cluster_
tests. A test is only skipped if all nodes support the requested capabilities, in _mixed clusters_ this might not be
the case: such a cluster can consist of a mix of nodes where some support respective capabilities and others don't.
However, in that case, the test is *not* skipped and you might randomly hit one of the nodes that actually supports
what you intended to skip on. This might break your assumptions and fail the test.
There was a problem hiding this comment.
and you might randomly hit one of the nodes
Worth mentioning this is "if there is no internal coordination on the cluster feature"? Or would this makes the text to complicated?
There was a problem hiding this comment.
I think we need some info like 'if not all nodes support the capabilities API itself, all capabilities are unsupported'
There was a problem hiding this comment.
I think we need some info like 'if not all nodes support the capabilities API itself, all capabilities are unsupported'
Do you really think that needs repetition @thecoop ? That should be clear based on the following just a few sentences above.
Only if every node in the cluster supports the requested path and method with all parameters and capabilities, the capabilities check passes successfully
There was a problem hiding this comment.
I think it should be blindingly clear and obvious here why capabilities skips won't work on mixed clusters - a single paragraph we can point people to HERE HERE HERE. This will come up, and people will be confused.
There was a problem hiding this comment.
@thecoop You're right, sorry I've misread. I'll change
There was a problem hiding this comment.
Wondering, should we discourage using capabilities in skip sections? Or not even support it?
There was a problem hiding this comment.
I think there is a use case (tests for previous behaviour)...
Document usage of Capabilities API in YAML REST tests (related to #108425 and #108678).