A test clicks "View invoice" and then looks for the invoice number. It fails, saying the element is not there.
The invoice opened in a new tab. Your test is still looking at the old one. Playwright did not follow the click, because pages do not automatically become the active one.
The fix has one detail that catches everybody, so read the order carefully.
const pagePromise = context.waitForEvent('page'); // start listening FIRST
await page.getByRole('link', { name: 'View invoice' }).click();
const newPage = await pagePromise; // now collect it
await expect(newPage.getByTestId('invoice-number')).toHaveText('INV-1024');
Start listening before the click. That is the whole trick. If you click first and then wait for the event, the tab may already have opened and you will wait for something that has happened, until the timeout.
Notice pagePromise has no await on the first line. You are storing the promise, not waiting for it yet. That is what lets the listener be active while the click happens.
After that, newPage is a normal page. Everything you know works on it.
To go back to the first tab, just use page again. Both stay open and usable, and you can move between them freely:
await newPage.close();
await expect(page.getByTestId('invoice-list')).toBeVisible();
Two related situations.
A pop-up window is the same thing. Playwright treats a pop-up as a page, and the same waitForEvent('page') catches it.
A link with target="_blank" is what causes most of these. If you only need to check the link's destination and not the page it opens, do not open it at all:
await expect(page.getByRole('link', { name: 'Terms' }))
.toHaveAttribute('href', '/terms');
That is faster and less fragile. Opening a new tab to check a link's target is work you do not need.
One piece of advice from real projects. Ask whether the new tab needs testing at all. Sometimes it opens a third-party page, a payment provider or a document viewer. Testing someone else's application is not your job, and those pages change without warning and break your suite. Check that the link points where it should, and stop there.
Remember this: listen for the page before you click, and think twice before testing a tab you do not own.
Reference: Pages and pop-ups.