Open source testing best practices, seven rules with file paths attached

Every top result for 'open source testing best practices' (RadView, BugBug, Opensource.com, GeeksforGeeks, Katalon, Aqua, testomat.io, TheCTOClub) gives rules at the architecture level: pick the right tool, integrate CI, use data-driven frameworks, build a team culture of testing. That advice is correct but under-specified. It never tells you what line of code a best practice looks like. This page does the opposite: every practice here is a file path and a line number in /Users/matthewdi/assrt-mcp on GitHub, under MIT. You can open the repo, read the 20 lines that implement the practice, and copy the pattern into your own test runner. That is what the word 'open source' actually buys you in a best-practices context, and it is the part the listicles omit.

Most modern signup flows render the 6-digit verification code as six single-character inputs, each with maxlength="1". When you type into the first box, the site auto-focuses the second box, and so on. An AI agent that types one digit at a time hits a race: the keydown handler moves focus mid-type, characters land in the wrong fields, verification fails. The fix is a synthetic paste event that dispatches all six digits in a single ClipboardEvent, because the split-field handler already has clean paste logic for exactly this case. The expression is in /Users/matthewdi/assrt-mcp/src/core/agent.ts between lines 234 and 236 as a template-literal instruction inside the SYSTEM_PROMPT constant: it selects an input[maxlength="1"], walks up to its parent, builds a DataTransfer, and dispatches a ClipboardEvent('paste') with bubbles and cancelable set to true. The agent evaluates that literal JavaScript via the evaluate tool, then calls snapshot to verify every digit landed. This is a best practice because it is the only reliable way to defeat the race, and it is documented verbatim in the prompt so the agent never tries to guess.

A fixed sleep is always wrong by one of two ways. If the page was ready in 400ms, you wasted 4.6 seconds across every test. If the page took 7 seconds (common on streaming AI chat responses), you asserted on half-rendered DOM and recorded a false fail. The best-practice alternative lives at /Users/matthewdi/assrt-mcp/src/core/agent.ts lines 956 through 1009, inside the wait_for_stable branch. It injects a MutationObserver over document.body with childList, subtree, and characterData tracking, counts mutations in a window.__assrt_mutations global, and polls every 500ms. The moment the mutation count goes 2 full seconds without changing, the primitive returns. A 30-second hard ceiling catches runaway pages. Fast pages return fast, slow pages wait as long as they need, and you never write a sleep again. Every top open source testing best practices post says 'prefer explicit waits over sleeps' but none of them ship the 50-line primitive that actually does it.

The code is at /Users/matthewdi/assrt-mcp/src/core/agent.ts lines 518 through 543 in the preflightUrl method. Before launching Chrome, the runner fires a HEAD request at the target URL with an 8-second AbortController timeout. If the HEAD 405s or 501s, it falls back to a GET. Any 2xx, 3xx, 4xx, or 5xx response is treated as reachable because the goal is to detect a wedged or unreachable server, not a broken endpoint. If the fetch aborts on the timeout or fails with a connection-refused, the runner throws a crisp error that names the URL and the timeout, instead of letting the Chrome launch hang for 3 minutes and then surface as an opaque 'MCP client not connected'. Multiply 3 wasted minutes by a flaky CI pipeline that runs 12 times a day, and this one 25-line method saves half an hour of debugging every week. Not one of the top 10 open source testing best practices articles mentions preflighting before the browser boots.

Hardcoded fixture emails (qa@example.com, test+timestamp@company.com) break two things. First, they collide across parallel test runs; the second run sees the first run's inbox. Second, they cannot receive real emails, which means you cannot close the verification loop and you assert on the UI state instead of the actual email delivery, missing whole classes of real bugs. The best practice is a single-use mailbox per test, and /Users/matthewdi/assrt-mcp/src/core/email.ts implements it in 130 lines against the temp-mail.io internal API. create() POSTs to /api/v3/email/new, getMessages() GETs the inbox, and waitForVerificationCode() polls every 3 seconds for up to 60, then extracts the code with a ranked list of patterns (code:, verification:, OTP:, PIN:, 6-digit, 4-digit, 8-digit). The agent creates one fresh address per scenario, so the test actually proves the email was sent and the code works, not just that the form submitted. This is the best practice nobody talks about because most guides test with mocked auth flows.

Browser-driving tests can only verify what the app shows you. When your app says 'Connected to Telegram', that banner does not prove a bot got the connection; it proves the app painted a green banner. The best practice is to verify the external side effect out-of-band. /Users/matthewdi/assrt-mcp/src/core/agent.ts lines 925 through 955 define the http_request tool: any method, any URL, any headers, any body, 30-second timeout, 4000-character response truncation. The agent uses it to poll https://api.telegram.org/bot<token>/getUpdates after a Connect Telegram click, call Slack's chat.list after posting a message, or GET /api/orders/<id> to confirm a checkout actually wrote to the database. This 'observe the side effect, not just the UI' best practice is standard in backend tests and almost never written into open source browser-testing guides, which is why it is the single highest-leverage rule on this page for any app that integrates with a third-party service.

A long-running browser test can easily fire 200 tool calls. If you naively slice the message list every N turns, you hit two errors. First, you orphan tool_use blocks from their tool_result blocks and the Anthropic API returns invalid_request. Second, you erase the first user message that contained the scenario, so the agent forgets what it is testing. The best practice at /Users/matthewdi/assrt-mcp/src/core/agent.ts lines 1060 through 1080 solves both: keep the first user message (the scenario), then walk forward through the tail until you find a role of 'assistant' or 'model' and cut there. That guarantees the slice starts at a safe boundary and never splits a tool_use/tool_result pair. Open source testing guides for non-AI tools never discuss this because it is AI-specific, but if you are building an LLM-driven runner, this is the rule you will discover the hard way in production and wish someone had written down.

CSS selectors (.btn-primary, [data-testid="login"]) are fragile because they encode layout that designers change and naming conventions that engineers refactor. The snapshot-first best practice, visible in the system prompt at agent.ts lines 206 through 218, flips that. Every interaction starts with a snapshot() call that returns the accessibility tree with [ref=eN] stable IDs for every interactive element. The agent picks 'e5' for the Sign up button from that snapshot, calls click with ref='e5', and never writes a CSS selector. When the underlying HTML changes, the accessibility role and name rarely do, so the ref selection survives. When the accessibility tree itself changes, the next snapshot returns fresh refs and the agent re-binds. It is the same principle as Playwright's getByRole but enforced at the runner level: no selector strings live in the test file or in the agent's memory across steps.