Smarter Waits in Broma: Replace Fixed Delays With Conditions
Every browser workflow has a timing problem. A click that works on your laptop at 9 a.m. can fail in a scheduled run because the page took two seconds longer to render. The usual fix is to add a fixed delay, but fixed delays only move the failure around. A better approach is to wait for a condition that describes the state your next step needs.
Why fixed delays fail
A fixed delay assumes a maximum load time. That assumption is wrong on real sites:
- Third-party scripts, fonts and images finish at different times.
- Dashboards load data after the shell appears.
- A slow API can leave a button visible but disabled.
- A validation message may appear after a save request completes.
When the delay is too short, the next step clicks nothing or types into the wrong field. When it is too long, every run is slower, and the workflow still fails on the one day the page is slower than usual. Fixed delays also hide the real problem: you never learn which element or state the workflow actually depends on.
A wait step should answer one question: what must be true before the next action is safe?
Four wait conditions that cover most web tasks
Element exists
Use this when a container, row or button is rendered late. The condition is usually a CSS selector.
#orders tbody tr
[data-testid='save-button']
.login-form input[name='email']
Wait for existence before you try to read or click. Do not wait for a selector that matches many elements if you only need one; scope it to a stable parent.
Element is visible and enabled
Existence is not enough. A button can be in the DOM but hidden behind a modal, or visible but disabled while a request is in flight. Use a short JavaScript expression when the app exposes disabled state.
(() => {
const b = document.querySelector('#save');
return !!b && !b.disabled && b.offsetParent !== null;
})()
This is more reliable than waiting two seconds and hoping the form is ready.
Text or value matches
Use this after search, save, filter or validation. Wait for the result the user would look for, not for a generic spinner.
document.querySelector('#status')?.textContent.trim() === 'Ready'
For tables, count rows:
document.querySelectorAll('#orders tbody tr').length > 0
For a toast, wait for the toast element, then read its text in the next step. That keeps the wait simple and lets you branch on success or error.
URL or route changes
Use this after login, redirects, checkout steps or any action that changes the page. A URL wait is often more stable than waiting for a page-specific element, especially when the destination page has multiple layouts.
Set the condition to the part of the URL that matters, such as /dashboard or order_id=, not the full URL with session parameters.
How to add a wait step in Broma
Broma is a Windows desktop app, and workflows run on your own computer. If you use an AI agent to draft a wait step, note that AI is not included in Broma's price; the agent runs on your own provider API key or your ChatGPT or Claude subscription.
- Select the action that is failing, such as Click or Type.
- Insert a Wait step immediately before it.
- Choose the target selector or page condition.
- Pick the condition: exists, visible, enabled, text equals, text contains, or URL contains.
- Set a timeout and a polling interval.
- Add a fallback branch for timeout: capture a screenshot, write a run-log note and stop or retry.
- Run the flow once on a cold page and once on a warm page.
Keep waits close to the action they protect. A single long wait at the top of a flow cannot cover every state change later.
Example: waiting for an orders table
An operations team opens a dashboard, filters orders and reads the first row. The table shell appears immediately, but rows arrive later.
Add a wait before the read step:
#orders tbody tr
Condition:
document.querySelectorAll('#orders tbody tr').length > 0
If the page also shows a loading spinner, add a second wait after the row count:
!document.querySelector('.loading-spinner')
Then read the first row. Set the timeout to 30 seconds for a batch run. If the table is empty because there are no orders, do not wait forever: branch on a visible empty-state message such as No orders found and handle that as a valid outcome.
Example: form save with success or error
A marketer submits a form and needs to know whether it saved. The save button disables while the request runs, then a toast appears.
Step 1: wait for the button to be enabled before clicking.
(() => {
const b = document.querySelector('#submit');
return !!b && !b.disabled;
})()
Step 2: wait for the toast element.
.toast
Step 3: read the toast text and branch:
document.querySelector('.toast')?.textContent.includes('Saved')
If true, continue. If false, capture a screenshot and log the text. This is better than waiting for a fixed five seconds and assuming success.
Timeouts, retries and fallbacks
Set timeouts from observed behavior, not from the fastest run. A good starting point is the 95th percentile load time plus a buffer. For interactive flows, 15 to 30 seconds is common. For batch runs on heavy dashboards, 30 to 60 seconds may be reasonable.
Use a polling interval around 250 to 500 milliseconds. Very tight polling adds load without making the workflow faster. Very loose polling makes the flow feel slow and can miss short-lived states.
On timeout, do three things:
- Capture a screenshot.
- Log the selector, condition and current URL.
- Stop with a clear error, or retry once after a reload if the page is known to be flaky.
Do not retry authentication failures or validation errors. Those need a human decision or a different branch.
Testing and hardening waits
Test waits the way pages actually fail:
- Run with a cold cache after restarting the browser profile.
- Throttle the network in a manual test to see which element appears last.
- Test the empty state, the error state and the slow state.
- Temporarily rename a selector to confirm the fallback works.
- Check that the timeout screenshot shows the page, not a blank tab.
Prefer stable selectors such as data-testid, name attributes and IDs tied to the component. Avoid long nth-child chains and text that changes with dates, prices or user names.
When a fixed delay is still okay
Fixed delays are not banned. They are fine for small animation settling after a condition is already true, for example a 200 to 500 millisecond pause before a screenshot. They are also useful as a polite pace between page loads when collecting public data. The mistake is using a delay as the primary synchronization mechanism.
Common mistakes checklist
- Waiting for an element to exist but not to be visible.
- Waiting for a button to be visible but not enabled.
- Waiting for a spinner to disappear when the spinner is removed before data arrives.
- Using a success message that is different for every record.
- Setting one global timeout for every step.
- Forgetting the empty-state branch.
- Capturing no evidence when a wait times out.
The goal is not to make every workflow wait longer. It is to make every workflow wait for the right thing. Once each action is protected by a clear condition, slow pages become a normal case instead of a mysterious failure.
