Skip to content

Cannot getByText() an h1 tag #187

Closed

Description

@Crell

Environment

  • playwright-php/playwright: 1.5.0
  • PHP: 8.4.26
  • Node.js: v24.21.0
  • Browser: chromium

How to reproduce

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-us" xml:lang="en-us">
    <head>
        <title>Sample page</title>
    </head>
    <body class="dashboard">

    <div class="breadcrumbs">Administration</div>
    <h1>Administration</h1>
    </body>
</html>
// In a PHPUnit test
$this->expect($this->page->getByText('Administration'))->toBeVisible();

Produces this failure:

Playwright\Assertions\Failure\AssertionException: Expected locator to be visible.

This assertion will fail, because the string "Administration" appears twice, not once. This is not obvious from the API nor from the error message, and is only implied as a concern in the documentation.

A better solution would be to expose the details of the failure better, such as "Text expected to be found once, but was found %d times" (or something.)

An even better solution would be to adapt the API to be clearer that something is being looked for once, or to allow it to appear multiple times.

Original report

I'm not sure I can provide a small replication, as I don't understand the issue.

I am just starting off with Playwright, and so far so good. My issue is I cannot seem to assert text that is in the <h1> tag of the page.

// Basic version of my test case
    #[Test]
    public function adminSuccess(): void
    {
        // 1. Go to the login page
        $this->page->goto('http://example.com/');

        // 2. Fill in the form
        $this->page->locator('#username')->fill('fakeadmin');
        $this->page->locator('#password')->fill('fakeadmin');
        $this->page->locator('input#login')->click();

        // 3. Assert that the login was successful

        // These all work as expected and pass.
        $this->expect($this->page)->toHaveURL('http://example.com/admin');
        $this->expect($this->page->getByText('Logout'))->toBeVisible();
        $this->expect($this->page->getByText('Welcome, fakeadmin'))->toBeVisible();

        // All of these fail for unclear reasons, even though that string is absolutely present in the page.
        $this->expect($this->page->getByText('Administration'))->toBeVisible();
        $this->expect($this->page->getByRole('heading'))->toHaveText('Administration');
        $this->expect($this->page->locator('h1'))->toHaveText('Administration');
    }

Expected behavior

From everything I can see, this assertion should be passing.

Actual behavior

The screenshot that is generated shows a nice big "Administration" string on the page. Looking at the page source, it is definitely there in the H1 tag:

<h1>Administration</h1>

And the string appears in the breadcrumbs, too. I also confirmed that the HTML is being delivered complete; it's not doing any ajax loading for that part of the page.

This happens on every page I've tested, not just the initial page after login. The text in the H1 is just not found, yet text in the header (the logout link, etc.) is.

I figure there's a 75% chance this is user error, but I am not sure what. Please advise.

Activity

  1. kbond commented on Nov 6, 2026

    @kbond
    Contributor

    Could you share the complete assertion failure or exception and a minimal HTML/CSS reproduction? We haven’t confirmed whether the merged fixes address this heading lookup issue.

  2. Crell commented on Nov 7, 2026

    @Crell
    Author

    I'll see if I can find a way to make a stand-alone replication on Monday when back at work.

  3. smnandre commented on Nov 8, 2026

    @smnandre
    Member

    I couldn't reproduce the issue with any of these assertions.

    Could there be something in your HTML or the text itself that's causing the problem? Is it really just <h1>Administration</h1>, or is there anything else that might explain this behavior?

    Have you tried dumping the locator counts to check whether you're matching too few or too many elements on the page?

  4. Crell commented on Nov 10, 2026

    @Crell
    Author

    OK, I was able to make a reproducer in PHPUnit. Long story short:

    <!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml" lang="en-us" xml:lang="en-us">
        <head>
            <title>Sample page</title>
        </head>
        <body class="dashboard">
    
        <div class="breadcrumbs">Administration</div>
        <h1>Administration</h1>
        </body>
    </html>
    // ...
    $this->expect($this->page->getByRole('heading'))->toHaveText('Administration');
    $this->expect($this->page->locator('h1'))->toHaveText('Administration');
    $this->expect($this->page->getByText('Administration'))->toBeVisible();

    The first two expects() work fine. The third one fails. But, if I remove or comment out the <div>Administration</div> part, then the 3rd line works. I also confirmed the order of elements doesn't matter.

    So getByText() appears to be actually doing getByTextButOnlyOnce(). Which is... unexpected.

  5. kbond commented on Nov 10, 2026

    @kbond
    Contributor

    Thanks for the repro! getByText('Administration') matches both the breadcrumb and the heading. toBeVisible() requires exactly one match. Playwright’s locator strictness docs

    You can target the heading directly:

    $heading = $this->page->getByRole('heading', ['name' => 'Administration', 'level' => 1]);
    $this->expect($heading)->toBeVisible();

    The confusing message is on our side. The PHP assertion hides Playwright’s error and should tell you that the locator matched two elements.

  6. Crell commented on Nov 11, 2026

    @Crell
    Author

    Shall I repurpose this issue into an error message bug, or make a new one and reference?

  7. kbond commented on Nov 11, 2026

    @kbond
    Contributor

    Let’s repurpose this issue for the error message bug. The reproducer and context are already here. “Preserve Playwright errors in assertion failures” would be a good title.

  8. Crell commented on Nov 11, 2026

    @Crell
    Author

    Title and description updated. Ball's in your court now. Cheers. 😄

  9. smnandre commented on Nov 15, 2026

    @smnandre
    Member

    Thank you for the reproducer, it made this quick to confirm.

    #226 fixes it: the assertion now fails at once and shows Playwright's error. With your HTML:

    Expected locator to be visible.
    locator.isVisible: Error: strict mode violation: getByText(/Administration/i) resolved to 2 elements:
        1) <div class="breadcrumbs">Administration</div> aka locator('div')
        2) <h1>Administration</h1> aka getByRole('heading', { name: 'Administration' })
    ... 
    
  10. added
    Has PRAn open pull request addresses this issue
    on Nov 15, 2026
  11. Crell commented on Nov 16, 2026

    @Crell
    Author

    That looks awesome, and would have saved me a ton of head scratching. 😄 Thanks!

  12. added a commit that references this issue on Nov 17, 2026
    5261656
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Has PRAn open pull request addresses this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions