This seems like a good candidate for the new capabilities feature here but I couldn't work out how to use it robustly. AFAICT ESRestTestCase#clusterHasCapability will throw an exception if the handling node doesn't even support the GET _capabilities API.

That looks like a bug @DaveCTurner, the behavior should match this:

I see yes that'd make more sense.

The 4-valued Optional<Boolean> is an awful return type here btw :) Doubly so since Optional.of(null) is impossible but Optional.empty() means two different things: if we get a response with a supported: null then that seems like it should be a test failure, whereas a 4xx error should just be false.

Actually I take that back, I see some point in distinguishing "don't know" from "definitely not supported". But maybe we could just return a nullable Boolean? Some Javadocs about the different return values would be very helpful here.

Yes, depending on if you require a capability or reject a capability you might want to treat that differently.
However, we still have an ongoing discussion on that point. Rejecting a capability isn't necessarily working as one might expect at the moment, despite returning false you might still randomly hit a node that DOES support the capability, TBD (cc @thecoop )

In which case it will return false indicating the capability is not supported.

This is a difference in behaviour - it could return #of(false) or #empty() depending on which node it hits...

The convention with Optional, of course, is to never return null. So it's 3-valued as it is the case for a nullable Boolean. But 💯 on the Javadocs, I'll update these in #108889 as well 👍