Clarify this.withVariation usage

[herzzanu]

It looks like in the docs we're documenting to use async this.withVariation I guess the async is for having the settled in here Do we really need the settled() helper at that point?

@achambers @SkoebaSteve any thoughts?

[SkoebaSteve]

I havre checked but I don't see a particular reason for this being there. I think we should create a branch removing it and see what impact it has for us, WDYT @herzzanu?

[aklkv]

Yes. withVariation calls context.set(key, value), which updates tracked state. Ember schedules the resulting re-render asynchronously. settled() ensures the DOM has fully updated before the test continues.

Without it:

this.withVariation('my-flag', true);
// ❌ DOM may still reflect the OLD value
assert.dom('.square').exists();

With it:

await this.withVariation('my-flag', true);
// ✅ DOM has re-rendered with the new flag value
assert.dom('.square').exists();

Why is it documented as async?

withVariation returns the Promise<void> from settled(). The async/await in the docs is telling callers to await that promise — not that the function itself does async work.

@RobbieTheWagner we can close this one as I have clarified API in #701