docs(skills): replace fixed sleeps with agent.waitFor

Merged
KA
4d ago
+67-6

The skills said "never add a sleep" but gave a coding agent nothing to put in its place, so a sleep was what it kept reaching for. They now name the replacement: agent.waitFor on the state the test was waiting for.

  • skills/e2e/SKILL.md: the step for fixing a failed test rules out sleeps and fixed delays and points to agent.waitFor('<that state>').
  • skills/e2e/references/agent.md: a bad/good example under waitFor, plus its limits: it needs a model even under a custom executor, it is never cached, and it judges on every screen change up to maxModelCalls, so for a long wait on a screen that keeps changing, raise interval.
  • skills/e2e/references/writing-tests.md: the Habits line waits for a state, not a duration. A matcher with a longer timeout is still the choice when a locator names the state exactly.
  • skills/migrate-to-e2e/SKILL.md: an old suite's sleep is ported as agent.waitFor, or as an assertion when a locator names the state or the config has no model.
// BAD: guesses how long the export takes.
await new Promise((resolve) => setTimeout(resolve, 10_000));

// GOOD: waits for the state, up to the timeout.
await agent.waitFor('the export finished and a download link appeared', { timeout: 60_000 });

The docs/migrate/*.mdx tables still map waitForTimeout and fixed waits to a locator assertion. That is still right when a locator names the state, so this PR leaves them alone.

Verified

Ran it locally: yes

  • Built e2e and ran npx e2e guide agent in apps/testbed: the new rule, example, and limits appear in the waitFor section the CLI serves.
  • pnpm plugins:check confirms the plugin copies match skills/.