Assertions Strategy - AI Instructions
When to use: Every time you write an
expect()call, wait for a condition. Prerequisites: locators for locator strategies used in examples.
Core Rules
MUST: Use expect from custom matchers (testExtends/customMatchers.ts)
MUST: Use Playwrights Web-First Assertions according to documentation
MUST_NOT: Compare against untranslated strings (use translation key validation)
String Validation Hierarchy
Apply in this order:
Translations (references from translation definitions in
suite/intl/src/messages.ts)await expect(header).toHaveTranslation('TR_SEND_TITLE');toHaveText (exact text match)
await expect(amount).toHaveText('1,234.56');Narrower locator or
toContainText(if element has other content)// ✅ Request narrower testid from product await expect(card.getByTestId('@dashboard/asset/price')).toHaveText('$45,000'); // ⚠️ Last resort if narrower locator unavailable, inform developer and discuss it await expect(card).toContainText('$45,000');
Do Not Duplicate Playwright's Implicit Checks
Playwright performs actionability checks (visible, stable, receives events, enabled) and auto-retries assertions automatically. Never add manual waits or pre-action expect calls to verify these.
Redundant code (❌ WRONG):
// ❌ WRONG: Manual wait before action, testing if enabled
await page.waitForTimeout(500);
await expect(button).toBeEnabled();
await button.click();
Anti-Patterns
❌ Hardcoded strings without translation:
await expect(header).toHaveText('Send Bitcoin');
❌ Hardcoded timeouts:
await page.waitForTimeout(2000);
❌ Using toContainText when narrower locator exists:
await expect(card).toContainText('0.5 BTC'); // might match other text
❌ one-liner that hides test intent
async verifyAmount(value: string) {
await expect(this.amount).toHaveText(value);
}