User-Visible Locators | Bondar Academy
Course: Playwright UI Testing with TypeScript
Module: Locators and Assertions
Instructor: Artem Bondar
Lesson Summary
In this lesson, you will learn how to use user-visible locators to locate web elements on a web page using Playwright . The main idea is to interact with web elements that are visible to users, avoiding reliance on implementation details. Key Concepts User-visible behavior: Automated tests should verify that the application works for end users, focusing on what users can see and interact with. Locators: Locators should mimic user behavior. For example, if users see the text on a button, the locator should also reference that text. Best Practices for Locators Use the following methods to create user-facing locators: getByRole : Identifies elements by their role. Example: await page.getByRole('textbox', { name: 'email' }) . getByLabel : Finds elements by their associated label. Example: await page.getByLabel('email').click() . getByPlaceholder : Locates elements by their placeholder text. Example: await page.getByPlaceholder('Jane Doe').click() . getByText : Uses static text displayed on the web page. Example: await page.getByText('Using the grid').click() . getByTitle : Finds elements by their title attribute. Example: await page.getByTitle('IoT dashboard').click() . getByTestId : Uses custom test IDs defined in the source code. Example: await page.getByTestId('sign-in').click() . In summary, user-facing locators, especially getByRole , are considered best practice in Playwright as they reflect actual user interactions. This approach enhances test reliability and aligns with user experience.
Video Transcript
In this lesson, you will learn how to use user-visible locators to locate web elements on the web page. The concept of user-visible locators was created by the Playwright, and the main idea is that we interact with the web element that are visible to the users. And Playwright has special methods related to user-visible locators, and in this lesson, I will show you the best practice how to use those locators to find the web elements. So let's get into it. So I'm on the best practices page in the documentation, and this page starts with the testing philosophy. And the first paragraph is test user-visible behavior. So let's go through this first paragraph. Automated tests should verify that the application code works for end users and avoid relying on implementation details, such things which user will not typically use, see, or even know about, such as the name of the function, whether something is an array or CSS class, or some element. The end user will see interact with what rendered on the page. So your test should typically only see interact with the same rendered output. So the general idea behind this philosophy is that our locator should mimic the user behavior. So if, for example, users see the text on the button, our locator also should contain the text that users see and specify that this is a button that we want to interact with. And if we go to our test application, for example, we have this user form, right? And we have a sign-in button. One way what we can do is to create, for example, some unique ID for this button and then use page.locator and click by ID. But user do not see this ID, right? User see a square button of certain color and with a text, sign in. And for example, if developer will delete this text by mistake, then it still will be a button. This button probably will still have an ID and it will be clickable. Our test will work, but it will not work from the user perspective. User will see some unknown square on the page and even may not know that this is a button. So it is important trying to use the locators that are user facing, that mimic what users see and how user interact with the application. And those types of locators, I will show you how to write right now. So I will start new test and I will call it user facing locators. So the main method that you would always try to use first called getByRole, this one. So what is role? Role is the type of the element that we're trying to interact with. There are 67 more, a pretty big list of those roles. And in Playwright documentation, you can check all available roles that you can use. And keep in mind that role is not necessarily a role attribute that assigned to the HTML tag. Role works a little bit differently. So I will not go into the details right now. Here is some area rules that follow behind those roles. You can read more details, what is area role and area attributes. And just with experience, you will find out the usage of most popular roles. And in this lesson and in upcoming lesson, I will show you different examples with different roles, how you can interact with different elements using this getByRole locator. So let's get started. I'm going back, getByRole. And let's say we want to find the locator for this email input field. So what should I type here? I get role is a text box, right? Is it a text box? Yes, sure. This is a text box. And this text box has a name, email. Well, that's simple. Does it look like user facing? Absolutely. So we are looking for the text box that has name, email. Look at this. This is a text box? Yes. Does it have email? Yes. But this is not unique. Unfortunately, we have a second text box on this page. So this locator will return us a to web element. So let's make a first and make a click. And we put a wait and run it. Email is this one, not this one. So we have one more email input field above. Anyway, so it found the text box that has text, email and click on the first email box that was found. Let me give you another example. Await page get by role. For example, let's find a button that has name, has object, name property and name sign in. And again, we have several sign in buttons. So I want to find the first one, first dot click and run it one more time. And here we go. We see the click was successful on sign in button. So that's the main idea behind get by role. I'm going to take some time and practice, but you'll get used to it and we'll use this approach efficiently. So what are other options for the user facing locators do you have? So let's do await page get by label. And we need to find any elements that has a label going back to test application. And for example, this is our email and email has a label email and click on inspect. Here we go. So this is our input field, right? It has a label tag and we can find this input field by the label. So we need to provide just a label name, email and find first dot click execute successful. So you can see we even we provided the label, which is this one, but we were looking for the input element. So and it was successfully clicked on the input element. So going back another example, await page get by placeholder. So placeholder, let's go in back and we have this input field over here. And we see the text Jane Doe, which we cannot change, modify or edit. This is actually a placeholder. And if I make inspect of this element and look into the DOM, here we go. We have a attribute placeholder Jane Doe. So we can take this value of the placeholder and use it as our locator get by placeholder. And this is most likely a unique element. So I can just perform click event right here and it should work. I run it. Yeah, it's perfectly worked. We make a click on Jane Doe. You can also search by just text. Await page get by text. We already used this locator when we were locating our menu items, form and form layouts. And again, you can provide any static text that is displayed on your web page as your locator. For example, if we take using the grid and we want to click on using the grid by text, this also will work. Okay, we can see we perform the click on using the grid. Another example, we can use await get by title. So title is also HTML attributes. Going back to application, we can go this. I click on IoT dashboard, inspect. This is the element for IoT dashboard and menu item. We can see that it has title attribute. So I can select this menu item by title. Get by title and dot click. I run it. And here we go. A click was successful. And the very last example in the list of get by methods will be page get by test ID. So what is test ID? Test ID is the identifier that you can define by yourself in the source code. This is also considered a pretty good practice when you have a dedicated attributes as a test IDs in your application. This will make your application also very resilient. But still, it's not kind of a user facing interaction because you interact with the locator that user physically cannot see. But still using test IDs can make your code very resilient. How to use test ID? So let's add into the source code our own test ID, for example, for this sign in button. Let me refresh. And what I need to search, I want to search in the source code, this sign in. I click on this search here. I type sign in and we have forms layout component HTML page. I'm clicking on that. And this is the source code of our application. We're looking directly into this. So let me compare. Yeah, here we go. This is option one, option two, disabled option. Going back, we have this option one, option two, and this is the button with our text signing. So what we need to do is to add an extra attribute, data dash test ID equals, and we provide our own name wherever we want. For example, sign in. Keep in mind that this keyword data test ID is reserved by playwright. And if you want to change it to something different, you can always override it into the playwright config settings. So now we're going back here and we provide the name of the sign in inside of the data test ID. Let me comment this out and try to run it. Yeah, as you can see, we successfully clicked on the sign in button based on the data test ID. So that's it, guys. Let me quickly summarize what we did in this lesson. I introduced you to the user-facing locators, and user-facing locators start with get by role, by label, placeholder, text, or by title. Get by role is specifying the role of the web element and the text of the web element you're trying to interact with. User-facing locators mimicking the actual user behavior and considered a best practice in the playwright to use as a preferred method of the locator whenever possible. All right, that's it, guys, and see you in the next lesson.