salesforce-waits
Skill1 starsChanged 3 months agoMITView on GitHub
Use when a Salesforce Lightning test needs to wait — record save, page navigation, spinner, toast, inline edit, list refresh — or when fixing a flaky Lightning test. Covers why /aura can't be matched by URL and what to wait on instead.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- ai-native-workflowSkill
- api-testingSkill
- bootstrapSkill
- common-tasksSkill
- configSkill
- data-strategySkill
- debuggingSkill
- enumsSkill
- fixturesSkill
- page-objectsSkill
- salesforce-authSkill
- salesforce-dataSkill
- salesforce-locatorsSkill
- salesforce-metadata-contractSkill
- salesforce-personasSkill
- salesforceSkill
- security-testingSkill
- selectorsSkill
- test-standardsSkill
- type-safetySkill
- wait-strategySkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Not discouraged — refused.
- Distinctive: line 19
Every Aura server action posts to the same endpoint:
- Distinctive: line 31
If you genuinely must wait on an Aura action, match the payload — but treat it as a smell:
- Very specific: line 63
Caveat worth knowing: not every Lightning surface uses the UI API.
- Very specific: line 120
If you need both the toast and heavier verification, assert the toast first.
- Distinctive: line 163
Don't fix this with a sleep.
- Very specific: line 176
Don't use networkidle. Refusal on this profile.
- Very specific: line 177
Don't wait on /aura by URL — it matches an unrelated background action.
- Distinctive: line 178
Don't assert a toast after doing other work.
- Distinctive: line 179
Don't wait for a spinner to disappear as your only readiness signal.
- Very specific: line 180
Don't raise a timeout to fix a Lightning flake.
- Distinctive: line 182
Don't assume every screen uses the UI API.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Salesforce Waits — Aura is not waitable, ui-api is
Extends wait-strategy. Everything there still holds: no waitForTimeout, pre-register before you
trigger, prefer web-first assertions. This skill covers what's Salesforce-specific.
networkidle is a refusal here
Not discouraged — refused. Aura fires server actions continuously, CometD holds a long-poll open
indefinitely, and the empty-approval/beacon traffic never stops. The network is never quiet for 500 ms, so
networkidle either hangs to timeout or resolves in a random gap. There is no org where this is safe.
Why you can't wait on /aura
Every Aura server action posts to the same endpoint:
POST /s/sfsites/aura?r=3&aura.ApexAction.execute=1
POST /s/sfsites/aura?r=4&other.action=1The operation lives in the form-encoded message payload, not the URL. So a URL-substring wait on
/aura matches the next Aura call — which is very likely an unrelated background poll that fires
milliseconds later. The wait resolves, your data isn't there, and you get a flake that's nearly
impossible to read.
If you genuinely must wait on an Aura action, match the payload — but treat it as a smell:
// Last resort. Prefer a ui-api wait or a DOM assertion.
const saved = page.waitForResponse(
(r) => r.url().includes('/aura') && (r.request().postData() ?? '').includes('Account.Save'),
);What IS deterministic: the UI API
Lightning's modern data layer (lightning/uiRecordApi, used by record pages, forms, and list views)
goes through versioned, identifiable REST endpoints:
GET /services/data/v62.0/ui-api/records/001... ← record load
PATCH /services/data/v62.0/ui-api/records/001... ← record save
GET /services/data/v62.0/ui-api/object-info/Account ← metadata + effective FLS
GET /services/data/v62.0/ui-api/list-records/... ← list view
POST /services/data/v62.0/ui-api/records ← record createThese are your wait targets. helpers/salesforce/lightning.ts wraps them:
waitForRecordLoad(page, recordId?) // GET ui-api/records
waitForRecordSave(page) // PATCH/POST ui-api/records
waitForObjectInfo(page, 'Account') // GET ui-api/object-info/<Object>
waitForListRecords(page) // GET ui-api/list-records
waitForUiApi(page, fragment) // escape hatch for any ui-api pathCaveat worth knowing: not every Lightning surface uses the UI API. Aura-era components and some
managed-package UIs still route through /aura. Confirm which path your screen actually uses by watching
the network in playwright-cli before choosing a wait — don't assume.
Recipes
Save a record
Pre-register the save, click, then assert the outcome. Two independent signals; assert the durable one.
const saved = waitForRecordSave(page);
await recordPage.save();
await saved;
// Assert the RECORD, not the toast — the toast auto-dismisses and will race you.
await expect(recordPage.fieldValue('Account Name')).toContainText('Acme Corp');Navigate to a record page
Lightning routes are client-side; the URL settles before the data does. Wait for both.
const loaded = waitForRecordLoad(page);
await listView.openRecord('Acme Corp');
await page.waitForURL(/\/lightning\/r\/Account\/[a-zA-Z0-9]{15,18}\/view/);
await loaded;Spinner
lightning-spinner renders role="status" with assistive text. Prefer asserting the content appeared
over asserting the spinner left — a spinner that never mounted makes toBeHidden() pass trivially
(the same false-green as the hashed-loader trap in wait-strategy).
// ✅ positive signal
await expect(recordPage.detailsRegion).toBeVisible();
// ⚠️ only as a secondary guard, and .first() because several may mount
await page
.getByRole('status', { name: /loading/i })
.first()
.waitFor({ state: 'hidden' });Toast
Auto-dismisses in a few seconds. Assert it immediately after the action, or not at all:
const saved = waitForRecordSave(page);
await recordPage.save();
await saved;
await expect(page.getByRole('status')).toContainText('was saved'); // do this firstIf you need both the toast and heavier verification, assert the toast first. Better: skip the toast and
assert the record — see salesforce (don't test the platform's confirmation chrome).
Inline edit on a record page
Three separate commits, each needing its own signal: open the cell, blur the input, save the panel.
await recordPage.editButton('Phone').click();
await fillAndBlur(recordPage.input('Phone'), '+1 555 0100'); // blur commits dirty flag
const saved = waitForRecordSave(page);
await recordPage.inlineSave.click();
await saved;List view refresh after a create
The list does not necessarily refresh on its own. Trigger it and wait on list-records:
const refreshed = waitForListRecords(page);
await listView.refresh();
await refreshed;
await expect(listView.row('Acme Corp')).toBeVisible();Concurrent calls
Same rule as generic: arm both, then trigger.
const saved = waitForRecordSave(page);
const relisted = waitForListRecords(page);
await modal.save();
await Promise.all([saved, relisted]);The hydration trap
Lightning renders the shell before components hydrate. A button can be visible and attached while its click handler isn't wired — the click silently does nothing and the test fails on the next assertion, pointing at the wrong place.
Don't fix this with a sleep. Wait for a signal that hydration finished — usually the record data arriving:
const loaded = waitForRecordLoad(page);
await page.goto(recordUrl(id));
await loaded;
await expect(recordPage.editButton).toBeEnabled(); // enabled, not just visibletoBeEnabled() over toBeVisible() is the cheap general defense here.
Don't
- Don't use
networkidle. Refusal on this profile. - Don't wait on
/auraby URL — it matches an unrelated background action. - Don't assert a toast after doing other work; it's gone.
- Don't wait for a spinner to disappear as your only readiness signal.
- Don't raise a timeout to fix a Lightning flake. The cause is almost always a missing pre-registered
wait or a hydration race —
debugging. - Don't assume every screen uses the UI API. Verify.
Checklist
- No
networkidle, nowaitForTimeout. - Waits target
ui-apipaths, not/aura. - Every response wait pre-registered before its trigger.
- Save asserted on the record, not only the toast.
- Navigation waits on both
waitForURLand the record load. - Text fields blurred before Save.
- Readiness asserted with
toBeEnabled()where hydration could race.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

