Skip to content
POMWright

Navigation

Every page object has a navigation helper, navigation, built from its baseUrl and urlPath. Its type, NavigationFor<BaseUrl, FullUrl>, follows the page object’s URL types: goto() without a target exists only when fullUrl is a string, and on a RegExp baseUrl goto(target) takes an absolute URL only. Each method is one Playwright call, with Playwright’s waits and timeouts, and a step of the report at the line that called it.

import { test } from "./fixtures";


test("the account link", async ({ loginPage }) => {
  await loginPage.navigation.goto(); // step: LoginPage: Navigate to this Page
  await loginPage.logIn("ada@shop.example", "correct horse");
  await loginPage.navigation.expectAnotherPage(); // step: LoginPage: Expect any other Page
  await loginPage.navigation.goto("/account"); // step: LoginPage: Navigate to https://shop.example/account
});

Guide: URLs and navigation.

Section titled “NavigationFor”

The type of a page object’s navigation, from its baseUrl type and its fullUrl type. A page object with string URLs has a NavigationFor<string, string>. Name the type to take the helper as a parameter:

import type { NavigationFor } from "pomwright";
import { test } from "./fixtures";


async function openAndLeave(navigation: NavigationFor<string, string>) {
  await navigation.goto();
  await navigation.expectAnotherPage();
}


test("the login page redirects", async ({ loginPage }) => {
  await openAndLeave(loginPage.navigation);
});

expectAnotherPage()

Section titled “expectAnotherPage()”

Waits until the browser has left this page, with one page.waitForURL(), and fails if it came straight back. See navigating.

Usage

await loginPage.navigation.expectAnotherPage({ timeout: 10_000 });

Arguments

Returns

  • Promise<void>

Throws

OrdersPage: expected to have left "https://shop.example/orders"; found "https://shop.example/orders" (page.waitForURL: Timeout 15000ms exceeded.)
OrdersPage: left "https://shop.example/orders" but returned to it; found "https://shop.example/orders"

expectThisPage()

Section titled “expectThisPage()”

Waits until the browser is on this page, with one page.waitForURL(), then runs the page object’s actions after navigation. See navigating.

Usage

await loginPage.navigation.expectThisPage();
await loginPage.navigation.expectThisPage({ runPostNavigationActions: false, waitUntil: "domcontentloaded" });

Arguments

Returns

  • Promise<void>

Throws

OrdersPage: expected URL "https://shop.example/orders"; found "https://shop.example/orders?tab=1" (page.waitForURL: Timeout 15000ms exceeded.)

Playwright’s error is the cause.

goto()

Section titled “goto()”

Navigates with page.goto(): without a target to fullUrl, then runs the actions after navigation; with a target to that URL, resolved against baseUrl as Playwright resolves one against baseURL, without the actions. See navigating.

Usage

await loginPage.navigation.goto();
await loginPage.navigation.goto("/account");
await loginPage.navigation.goto("?tab=2", { waitUntil: "domcontentloaded" });
await loginPage.navigation.goto("https://help.shop.example/");

Arguments

  • target string (optional)

    A path, a query, or an absolute URL. On a RegExp baseUrl, an absolute URL. Without it, the page itself; that form exists only when fullUrl is a string.

  • options NavigationOptions, or ThisPageOptions without a target (optional)

Returns

  • Promise<void>

Throws

What page.goto() throws. From JavaScript, on a page object whose URL is a RegExp:

AccountPage: goto() without a URL needs a string fullUrl; this page object has a RegExp URL. Pass an absolute URL instead.
AccountPage: goto("/account") needs an absolute URL because baseUrl is a RegExp.
Section titled “NavigationOptions”

The options of every navigation method, and the type of a page object’s navOptions. Each option comes from the call, then from navOptions, then from Playwright; see options and timeouts.

timeout

Section titled “timeout”

number (optional)

The limit of the method’s one waiting call, in milliseconds. Defaults to the project’s navigationTimeout.

waitUntil

Section titled “waitUntil”

"load" | "domcontentloaded" | "networkidle" | "commit" (optional)

The load state to wait for, as page.goto() and page.waitForURL() take it. Playwright’s default is "load".

ThisPageOptions

Section titled “ThisPageOptions”

The options of goto() without a target and of expectThisPage(): timeout and waitUntil, and:

runPostNavigationActions

Section titled “runPostNavigationActions”

boolean (optional)

false skips the page object’s actions after navigation for this call. Defaults to true.

UrlMatcher

Section titled “UrlMatcher”

The fullUrl of a page object whose baseUrl or urlPath is a RegExp: a URL predicate that tests the origin against the base and the rest of the URL against the path, which page.waitForURL(), toHaveURL() and page.route() take.

await expect(page).toHaveURL(accountPage.fullUrl);
const onAccountPage = accountPage.fullUrl.test(page.url());

See pages whose URL varies.

base

Section titled “base”

string | RegExp

The baseUrl the page object was constructed with.

path

Section titled “path”

string | RegExp

The urlPath the page object was constructed with.

test()

Section titled “test()”

Tests a URL, as the predicate does.

Arguments

  • url string | URL

Returns

  • boolean

toString()

Section titled “toString()”

A readable form, used in step titles and error messages: origin "https://shop.example" + path /^\/account\/\d+$/.

Returns

  • string