CSS selectors, the three run modes, and getByRole

• The CSS selector cheat sheet: combinators, attribute selectors, positional selectors
• Which CSS pseudo-classes you can skip in Playwright, and why
• Three ways to run a test: UI mode, debug mode, headed and headless
• Why a command-line flag beats the config file
• The locator priority ladder, and the 80% claim behind it
• ARIA, the accessibility tree, and the roles HTML gives you for free
• getByRole, and why name is the accessible name and not the name attribute
• What exact true changes about name matching
• A link that looks like a button, and why the role is still link
• Why getByRole returns a Locator rather than a Promise

Last class ended with the project set up and one task: open the site, click, and type a username and password. A good number of the room had it working, so this session closes out CSS and then starts the topic the rest of the month is built on.

The shape of the locator story, now that three of its four parts are done:

• Normal locators, the classic four hooks: id, name, class, tag.
• XPath, covered last class along with strict mode.
• CSS selectors, finished today.
• Playwright default locators, started today, and the ones you will actually use.

The combinators, which are the part people reach for daily:

Attribute selectors, which mirror what XPath already gave you:

Positional selectors, for when nothing else distinguishes the element:

li:first-child          the first one
li:last-child           the last one
li:nth-child(3)         the third one
li:nth-child(2n)        every even one
li:nth-child(2n+1)      every odd one

And the standing warning that applies to every one of these: prefer stable anchors. A framework-generated class like text-input W(100%) or an obfuscated data-qa="hocewoqisi" changes on the next build. A long positional chain breaks the moment a row is inserted.

Worth getting straight, because two of them sound the same and are not.

UI mode is the one to learn. It is closer to a debugger than a runner. You get the test list, a step-by-step timeline you can scrub, and for any step: the locator it used, the network requests in flight, console output, attachments, annotations and errors. You can click back up the timeline and see the page as it was at that step. Anyone who has used Cypress will recognise the shape of it immediately.

--debug is the smaller tool: it steps the test one command at a time in the Inspector, without the timeline and network panes.

This is the sequence to walk when you meet a new element. Try each rung, and only drop to the next when the one above cannot reach it.

ARIA is Accessible Rich Internet Applications, a set of roles and attributes that make web content usable by people with disabilities. Every modern browser builds an accessibility tree alongside the DOM, and developers are expected to write markup that produces a sensible one.

That tree is what getByRole reads. This is the whole idea: instead of asking "which element sits at this CSS path", you ask "which element on this page plays this role and answers to this name", which is the same question a screen reader asks.

Most roles you never have to set, because HTML already implies them:

This is where the class spent its time, and it is worth the space.

The second argument to getByRole is an options object, and the option everyone uses is name. It looks like it should match the HTML name attribute. It does not. It matches the accessible name, which is what a screen reader would announce for that element.

Here is the real VWO login field, which has both:

<input type="email" class="text-input W(100%)" name="username"
       id="login-username" data-qa="hocewoqisi" placeholder="Enter email ID">

The HTML name is username. The accessible name is Email. Passing username finds nothing; passing Email works. That failure happened live in class before the explanation landed, which is the right order to meet it in.

The spec pushed during the session, quoted from the repository:

import { test, expect } from '@playwright/test';

test("login form fields by role", async ({ page }) => {
    await page.goto("https://app.wingify.com/#/login");

    const username = page.getByRole("textbox", { name: "Email", exact: true });
    const password = page.getByRole("textbox", { name: "Password" });

    await username.fill('admin@vwo.com');
    await password.fill('1234');
});

What exact changes

By default, name matching is case-insensitive and substring-based. So name: "Email" would also match an element whose accessible name is "Email Address", and name: "appointment" matches "Make Appointment".

exact: true turns that off: the whole name must match, case-sensitively.

page.getByRole("link", { name: "appointment" })                   // matches
page.getByRole("link", { name: "make appointment" })              // matches, case-insensitive
page.getByRole("link", { name: "Make Appointment", exact: true }) // matches
page.getByRole("link", { name: "appointment", exact: true })      // does NOT match

The other spec pushed during the class, and it exists to make exactly one point.

import { test, expect } from '@playwright/test';

test("navigate via the Make Appointment link", async ({ page }) => {
    await page.goto("https://katalon-demo-cura.herokuapp.com/");

    const mainButton = page.getByRole("link", { name: "Make Appointment", exact: true });
    await mainButton.click();
});

On screen that control is a large, solid, button-shaped thing. In the markup it is an <a>, so the browser reports it as a link, and getByRole("button", ...) finds nothing at all. The class name on it is a costume.

A small thing that caused a visible wobble mid-class, and worth pinning down because it changes how the code reads.

const username = page.getByRole("textbox", { name: "Email" }); // Locator, returned immediately
await username.fill('admin');                                  // Promise, must be awaited

getByRole and the rest of the getBy* family are synchronous. They return a Locator, which is a description of how to find an element, not the element itself and not a promise. Nothing has touched the page yet. Putting await in front of it is harmless but does nothing.

The actions and assertions are the async part. fill, click, check, textContent and expect(locator).toBeVisible() all return promises and all need await.

Stated plainly at the end of the session, and it is the argument for the whole approach:

• No dependence on id attributes that the app may not have.
• No dependence on the name attribute.
• No breakage when a dynamic class name changes between builds.
• Shadow DOM stops being a special case, because the accessibility tree is flat.
• The locator reads like the requirement: find the textbox for the email.

A method demonstrated live rather than described, and the reason it was: the instructor will not be sitting next to you when a locator fails at 11pm.

Open Claude in the same folder as your test, point it at the exact element and the exact line that is failing, and ask it to explain using the explain like I'm five skill. The jacket-and-sign explanation of the accessible name in this page came out of doing precisely that, live, on the failing name: "username" call.

• There is a test tomorrow at 9:00 AM. It covers coding, JavaScript and TypeScript. The window is twelve hours, 9:00 AM to 9:00 PM, but the recommendation was to sit it in the first hour rather than leave it.
• Post doubts in the doubt thread, not scattered in chat, so they can be picked up in the next session.
• Two questions were explicitly deferred to the next class: a live walkthrough of debugging and fixing a broken locator, and the email validation case raised during the getByRole examples.
• Perspective offered on the workload: roughly 200 JavaScript and TypeScript exercises are behind the batch, and roughly another 200 Playwright exercises are ahead of it. Shadow DOM, SVG, web tables, dropdowns, alerts, windows and frames are all still to come, and the point made was that none of them are hard once the locator model is solid.