Reliable AI-Generated Tests

Use this checklist when asking a coding agent to write or review thirtyfour automation. It is intentionally short enough to paste into project-level agent instructions:

- Use WebDriver::managed for local browsers; use WebDriver::new or builder only
  when connecting to a remote Selenium or Grid endpoint.
- Use query() for normal lookup. Use find() only for an intentional one-shot lookup.
- End unique queries with single(), and add desc(...) to important queries.
- Prefer By::Testid or another stable app-owned selector. Avoid generated classes,
  DOM-position chains, and XPath when stable CSS can express the target.
- Never use a fixed sleep for page readiness. Wait with query() or wait_until().
- Scope queries through a container element; use Components for repeated UI areas.
- Explicitly call driver.quit().await? when the session is finished.
- Do not share one WebDriver session across independent concurrent flows. A shared
  WebDriverManager may launch separate sessions for parallel tests.
- Keep CDP and BiDi code isolated from portable WebDriver flows. Gate optional
  cdp-events and bidi APIs with their Cargo features, and opt BiDi sessions in.

Why These Rules

• WebDriver::managed downloads, launches, and lifetime-manages a local driver. Use the normal constructor or WebDriver::builder when an external Selenium service owns that lifecycle. Explicit quit() reports shutdown errors and does not rely on asynchronous cleanup during Drop.
• Element queries poll for page state and provide filters, descriptions, and cardinality checks. See the guidance for stable selectors, choosing single() or first(), describing important queries, and intentional one-shot lookup.
• Element waits express the state an existing element must reach. A fixed sleep only guesses how long the page needs; a query or wait completes as soon as the required state exists and produces a useful timeout when it does not.
• Element-scoped queries prevent unrelated matches. For recurring UI areas, Components keep selectors private and expose user-intent methods while their resolvers handle polling and stale elements.
• A cloned WebDriver controls the same browser session, so independent flows can race over tabs, navigation, and browser state. The manager’s shared configuration can instead launch a separate session for each test or worker.
• CDP is Chromium-specific, while BiDi is the cross-browser W3C protocol. Keep either behind a small boundary so the rest of the automation remains portable, and follow the feature flag and BiDi opt-in requirements. The cdp feature is enabled by default; cdp-events and bidi are opt-in.

Treat these as review rules, not merely generation hints: generated code should not be accepted until its selectors, waits, cleanup, concurrency, and feature gates satisfy the same checklist.