noctcore-code-quality/prefer-web-first-page-assertions
noctcore-code-quality/prefer-web-first-page-assertions
- Package
- code-quality v1.0.0
- Preset
- none opt-in
- Severity
- off
- Autofix
- No
- Suggestions
- Yes
- Options
- Optional
- Type info
- Not needed
Assert on the page with toHaveURL / toHaveTitle, which retry, not on a URL or title read once.
expect(page.url()).toBe(...) reads the address bar once, at whatever moment the line runs, and
compares the copy. After a click that redirects, that moment is often before the navigation lands,
so the test fails on a slow run and passes on a fast one. await expect(page).toHaveURL(...) retries
until the URL matches or the timeout runs out. The same goes for page.title() and toHaveTitle.
eslint-plugin-playwright’s prefer-web-first-assertions covers locator reads (textContent(),
isVisible(), inputValue()) but not the page itself, which is why projects add a
no-restricted-syntax selector for expect(page.url()). This rule replaces that selector and also
covers the title, a page object’s this.page, and expect.soft.
What it flags
Section titled “What it flags”page.url() or page.title() (called with no arguments, also after await) anywhere inside the
subject of expect(...) or expect.soft(...): directly, or inside an expression such as
new URL(page.url()).search. The receiver is a binding named in pages, or a member with that name
(this.page, ctx.page).
test('signs in', async ({ page }) => { await page.getByRole('button', { name: 'Sign in' }).click(); expect(page.url()).toBe('http://localhost:5173/dashboard'); expect(new URL(page.url()).searchParams.get('tab')).toBe('billing'); expect(await page.title()).toMatch(/Dashboard/);});test('signs in', async ({ page }) => { await page.getByRole('button', { name: 'Sign in' }).click(); await expect(page).toHaveURL('http://localhost:5173/dashboard'); await expect(page).toHaveURL((url) => url.searchParams.get('tab') === 'billing'); await expect(page).toHaveTitle(/Dashboard/);});Suggestions
Section titled “Suggestions”When the statement is expect(page.url()).<matcher>(expected); in an async function, the rule
offers a rewrite to await expect(page).toHaveURL(expected); (toHaveTitle for the title),
keeping .not and expect.soft. It does so only where the retrying matcher reads expected the
same way: after toBe, toEqual and toStrictEqual, and after toMatch with a regex literal.
toContain, toMatch with a string, and a computed subject (new URL(page.url()).search) get no
rewrite: write a regex or a predicate (toHaveURL((url) => ...)) by hand. It is a suggestion, not
an autofix, because toHaveURL resolves a relative string against the configured baseURL.
What it does not flag
Section titled “What it does not flag”- A read inside a block Playwright already retries: the callback of
expect(async () => ...).toPass()and the getter ofexpect.poll(() => page.url()). - A read outside the subject:
const before = page.url(), orexpect(other.url()).toBe(page.url())where it is the expected value. - Other receivers:
response.url()afterwaitForResponseis a fixed value, so reading it once is right. - Locator reads (
expect(await locator.textContent())); use eslint-plugin-playwright’sprefer-web-first-assertionsfor those.
Limitations
Section titled “Limitations”A read stored first and asserted later (const url = page.url(); expect(url).toBe(x)) is not
followed. A fixture with another name (adminPage) is not matched until you add it to pages.
Options
Section titled “Options”| Option | Type | Default | Meaning |
|---|---|---|---|
pages |
string[] |
["page"] |
Names of the page fixture, matched as a binding (page.url()) or a member (this.page.url()). |
// Playwright specs only, with a second page fixture.{ files: ['e2e/**/*.spec.ts'], rules: { 'noctcore-code-quality/prefer-web-first-page-assertions': ['error', { pages: ['page', 'adminPage'], }], },}When not to use it
Section titled “When not to use it”Outside Playwright specs. Puppeteer, WebdriverIO and Jest have no toHaveURL on the page, and a
page.title() there can be an unrelated record. That is why the rule is not in recommended:
enable it with a files glob for your specs.