Locator Syntax Rules | 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 the locator method in Playwright to find various web elements on a page. The lesson covers the syntax rules for locating elements by ID , attribute , tag , and more. Key Concepts Git Usage : Create a new branch for this lesson, write code alongside the instructor, and commit your changes at the end. This practice will help you become familiar with Git. Locator Syntax Rules : By Tag Name : Use the tag name as a string. For example, page.locator('input') . By ID : Prefix the ID with a hash sign. Example: page.locator('#input-email1') . By Class : Prefix the class with a dot. Example: page.locator('.shape-rectangle') . By Attribute : Use square brackets. Example: page.locator('[placeholder="email"]') . Combining Selectors : Combine tag and attribute without spaces. Example: page.locator('input[placeholder="email"]') . XPath : While possible, it is not recommended. Example: page.locator('//input[@id="input-email1"]') . Text Matching : Use page.locator({ text: 'partial text' }) for partial matches and page.locator({ text: 'exact text' }) for exact matches. Important Notes The locator method returns all matching elements. If multiple elements are found, actions like click require a unique locator. Use await with actions that return promises, such as click . In the next lesson, the focus will shift to user-facing locators , which are considered best practices in Playwright.
Video Transcript
In this lesson, you will learn how to use method locator of the playwright to find different web elements on the page, and also what is the syntax rule for this method are applied to find elements by ID, by attribute, by tag, and so on. And by the way, don't forget to use Git. Create a new branch for this lesson, write the code along with me, and then at the end of this lesson, create commit and push your code to the remote repository. And for every upcoming lesson, create a new commit. This way, you will practice using Git starting from this section. All right, so let's get in to locator syntax rules. So this is our test application, and I am on the Forms Layouts page. Today, I will show you how to use playwright to find different elements on this web page. And for example, we take this email input field for using the grid form, and I click Inspect, and here is the input field. We have input tag, we have different attributes for this tag, we have ID over here, we have CSS selector, where is our class? Here is our class with different values and parameters. So I will show you how to find this and locate this input element in the playwright. Going back to our project, and let me quickly refactor this to prepare for this class. So I will take this step, navigating to the Forms, into the BeforeEach, and Form Layouts also will put it back to BeforeEach. And I will remove these two test describes, we don't need them, and create a new test, LocatorSyntaxRules. Okay, here is our test body, and let's begin. So, let's talk about how to find the locator by tag name, page. and the most common method to find the locator in the playwright called Locator. Locator method will accept two arguments. First is a string for your locator, and second is the object for the different options of the locator. About the options we will talk about later, let's talk about the very first part, about the element that we want to provide here. So, in order to find the element by the tag name, we just need to provide a tag name as our input string. So, in our example, our tag name is input. So we type here, input, that's it. So input is not a unique element for this page, because if we go back, you can see that we have many other input fields over here. So, the playwright will find for us all those web elements and return of all those elements. So, keep in mind. The next step, how to find by ID. Page.locator and the syntax rule for the ID. In our example, we have ID input email one, I just copied directly from the code, and I put a hash sign, and then the value of the ID. So, that's how to find the element by ID. Moving on. How to find by class value. Page.locator and class value. We're looking for the class. This is our class, and this is the class that we have. We have input full wide, size medium, status basic, shape rectangle, and NB transition. For example, this one, shape rectangle. I want to find all that web elements that have class value, shape rectangle. Going back, put shape rectangle. And in order to specify that this is a class value, I put dot in front of this value. So, playwright will know that this is a class. If I will remove a dot, it will be a tag. If I put a hash sign, it means I'm looking by ID. But if I put a dot, it means I'm looking by class. Moving on. How to find by attribute. Page.locator, single quotes. And we have many different attributes over here. And let's say we want to find by attribute placeholder with value email. Copy this. And to find web element by any HTML attribute, we put square braces and put value inside of it. That's it. So, playwright will find for us all web elements that has placeholder email attribute inside of the DOM. Moving on. How to find by entire class value. I put it like full value. It's very similar like by attribute with only difference that we need to provide the full class value with all the values that it's inside of it like this. So, class, input, size, medium, and so on. So, as I mentioned before, class has kind of a special role in the HTML DOM structure. So, you can either find a web element by the entire class as an attribute or use just a separate values of the class using a dot notation. What else? You can also combine different selectors. So, you can use a combination. Let me show you. Page.locator. For example, you want to find web element by tag and by attribute. So, you want kind of make this more unique because input is very general tag name, but input in combination with placeholder email create a more unique web element. So, how to do that? It's just simply put them together one by one. Input and then next to it placeholder email. Important not to put a space over here. So, they should be like all together. And you can add if you want the other values as well. For example, attribute and you want to add a class. This will work as well. Or if you want to have second attribute, this will work as well. For example, we want to use nbinput. So, we can, in this case, add a second attribute, nbinput, and it will work. So, Playwright will find match for the web element that have all three attributes as part of the web element. It will return us all elements that have a match for that. Also, you can find elements by XPath. I think most of you are familiar with the XPath and the way to do it is page.locator. And for example, we want to use this id as our locator. So, I put star at id equals to input email one. So, XPath will work in Playwright as well. But this is not recommended. And I want to show you the reference to the Playwright documentation over here. So, Playwright says like, danger, we recommend prioritizing user-visible locators like text or accessible role instead of using XPath. That is tied to the implementation in easy break when page changes. So, about user-visible locators, we will talk about the next lesson. But just for your information, according to the Playwright, it is really not recommended approach and considered not a good practice to use an XPath. I know that most of the Selenium users prefer to use the XPath because they just got used to, but their frameworks evolved and they became more modern. And right now, with the modern frameworks like Playwright, using XPath is not recommended approach anymore. So, and two other things that you can do with a locator. Let's say you want to find the element by partial text match. So, we will use page locator and we provide column text. And then we give a text that we want to find on the page. For example, we have this form using the grid. And if we take just first word of using the grid and provide using, it will find a locator for us. And also, you can find by exact text match. It will look like this, page locator. And then it will be column text is and provide the full value of the text using the grid. All right, that's it. So, this is the main syntax rules and let's try to run it. And I will show you something interesting about it. To run the test, I will use NPX Playwright test in UI mode. Okay, this is our UI mode and this is our test. So, let me try to run it and what we see. So, the page was open, but we can see that nothing actually happened, right? So, the rest of the code, the rest of the locators were not actually called. We just click on the forms layout and that's it. Playwright didn't try to find any of our element. Why is that happened? Because Playwright will do anything with the web element only when we trigger any action for the web element. For example, I'll trigger the action for this particular locator, which is our ID for input email one. And I would use a method click. And since click is our action method that returns a promise, I need to use a wait in front of it. And let me run it one more time. And we can see that now it successfully clicked on the email field that we was trying to locate. And let me show you a different example. What if I try to click on the first element? Click over here and I need to use a wait. And by the way, look at this await when I remove the click. Await has no effect on this type of the expression. Why? Because locator is not a promise. Locator has a locator type. So that's why await is not needed when we just use a locator without any action method that returns a promise. Click is a promise, locator is not. That's why here we need await and here we don't need to use await. And let me run it one more time. And I will show you what happens when Playwright return a list of the web elements. So I run it. And we see the error message. If I scroll a little bit down here. So Playwright telling that error streak violation, locator input result 20 elements. So Playwright found 20 input elements on this webpage and it was not able to click. And also it's, look, it is providing us the different locator suggestions for each of the web elements, each of 20 elements. But if we do something like first, we say like, hey, Playwright, click for us on the very first input element that you have found. And we try to run it one more time. Yep, the very first input element is this one and it was successfully able to click. So let's quickly summarize what we did in this lesson. So let's quickly summarize what we did in this lesson. Locator is a general method in Playwright that you can use to find web elements on the webpage. The syntax rules is for the tag name, you use just the name of the tag name. For ID, you use a hash sign. For the class, you use a dot notation. Attributes should be in the square braces. If you want to combine the different web elements and different selectors, you just put them one by one. You can combine tags and attributes together. You can use also X-Bot, but this is not recommended way of finding elements in the Playwright. And also you can use a text to find the web element using partial match or using the exact match. Locator method will always return all available elements that had a match for this particular element. And if it is not unique, Playwright will not be able to act on this element. In order to perform any action, your element and your locator must be unique. So that's it, guys. And in the next lesson, we will talk about the user-facing locator that is considered a Playwright best practice to find the web elements. Thank you and see you in the next lesson.