name: playwright

For more details on Playwright best practices see <https://playwright.dev/docs/best-practices>

Automated tests should verify that the application code works for the end users, and avoid relying on implementation details such as things which users will not typically use, see, or even know about such as the name of a function, whether something is an array, or the CSS class of some element. The end user will see or interact with what is rendered on the page, so your test should typically only see/interact with the same rendered output.

Each test should be completely isolated from another test and should run independently with its own local storage, session storage, data, cookies etc.

Only test what you control. Don't try to test links to external sites or third party servers that you do not control, unless it is specifically for testing purposes.

Locators come with auto waiting and retry-ability. To make tests resilient, we recommend prioritizing user-facing attributes and explicit contracts.

1. getByRole to locate by explicit and implicit accessibility attributes ⭐⭐⭐⭐⭐

2. getByText to locate by text content

3. getByLabel to locate a form control by associated label's text

4. getByPlaceholder to locate an input by placeholder

5. getByAltText to locate an element, usually image, by its text alternative

6. getByTitle to locate an element by its title attribute

7. getByTestId to locate an element based on its `data-testid`

The filtering locator **must be relative** to the original locator and is queried starting with the original locator match, not the document root. Therefore, the following will not work, because the filtering locator starts matching from the `<ul>` list element that is outside of the `<li>` list item matched by the original locator:

There is `hasNot` which does the opposite of `has`.

Locators are strict. This means that all operations on locators that imply some target DOM element will throw an exception if more than one element matches. For example, the following call throws if there are several buttons in the DOM:

For more info on selectors refer to <https://playwright.dev/docs/locators>

If you encounter challenges when writing tests, it may be tempting to work around them (e.g. by using timeouts, sleeps, or brittle selectors). DO NOT DO THAT! Instead, try to make the app more testable first. Maybe adding semantic attributes (best), data attributes, or test IDs. For example, if a test script clicks the button too fast (before it is ready to be clicked), consider adjusting the app to initially disable the button until it is really ready to be clicked.

When testing a web page, sometimes unexpected overlays like a "Sign up" dialog appear and block actions you want to automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making them tricky to handle in automated tests.

The `addLocatorHandler` lets you set up a special function, called a handler, that activates when it detects that overlay is visible. The handler's job is to remove the overlay, allowing your test to continue as if the overlay wasn't there.

Running the handler will alter your page state mid-test. For example it will change the currently focused element and move the mouse. Make sure that actions that run after the handler are self-contained and do not rely on the focus and mouse state being unchanged.

To set up structure for page objects, extend the base `test` and `expect` functions:

Create a context interface for page objects:

Create an AppTester, the root page object:

Create a page object for each page in your app. For example, a LoginPageTester:

A page object:

- Is a class.

- Has a constructor that takes a `PageObjectContext`.

- Exposes methods and properties that represent user actions and elements on the page.

Now it can be used in tests:

Note: Work iteratively and don't create a premature abstraction! Use existing page object if possible. If not, don't create a new page object just yet! Implement it directly inside the test, and get it working first. Once working, analyze your test script to see if the hardcoded behavior should be added to a an existing page object or a new page object should be created.