This lesson covers the basics of Playwright's testing API such as the page object, locator, locator methods and expect.
Instructor: [0:00] To demo the fundamentals of Playwright test API, we create a new file called basics.spec.ts. The two key imports that you will need in order to create a Playwright test are test and expect.
[0:12] We get them from the playwright/test package. Now, one good thing that I want to point out about Playwright is that unlike Mocha or Jasmine on Jest, Playwright does not work with globals.
[0:21] This means that these imports will not fight with global testing packages that you might have and can be used perfectly fine with Jasmine, Jest, and Mocha.
[0:30] To create a basic test, we use the test function, provide a nice string for the test name, which we are calling math works, and then provide an async function, which will be executed when we want this test to run.
[0:42] We can use the expect method to assert any behavior within our code. For example, we can assert the fact that one plus one should be equal to two.
[0:51] To run the test, we do the same thing that we did before which is open up the terminal and execute NPX Playwright test, but this time since we only want basic start spec.ts to execute, we can pass the path to this file. Additionally, instead of running it across all the browsers, we can specify that we only want to run it with Chromium by using --project = Chromium.
[1:13] Finally, instead of the test results going into Playwright report, we just want to see them log to the console, so we can use --reporter is equal to list. When we run this command, no surprises, it works exactly as you would expect.
[1:28] Like other testing frameworks, Playwright also allows you to use .only to run one test. For example, here we are creating a test called page demo and we only want this test to run for now. Therefore, we use test.only.
[1:42] Playwright tests get access to a page object that has passed to the test function. We can use this page object to interact with the particular tab within a browser. For example, we can use the method page.goto, to navigate to a particular URL.
[1:57] Just so that we can see this navigation on screen, we'll add a delay of two seconds after this page.goto. We've been running Playwright in headless mode, but we can pass in an additional argument called --headed so that we can see the browser executing our test.
[2:12] You can see that we navigate to google.com, wait for two seconds and then the test completes. One key method within the page object is page.locator, which can be used to get access to elements so that we can interact with them on the page.
[2:27] For example, when you visit google.com, we have this input element where you will type in your search query. Now, a good way to select this particular input right now that I can see, is using input such that the title is equal to search. We jump back to our code and use page.locator, passing in a simple CSS selector for this particular input element.
[2:48] We are selecting input such that the title attribute is equal to search. Then we can interact with this element. For example, we can use the type method on the locator to send it some text. To send special characters to a locator, we use the method called press, which takes special character sequence.
[3:06] For example, we enter string in order to send it the enter keystroke. Now, if we execute this test, the browser will navigate to google.com input the text, "Hello egghead" and then perform a search by pressing the enter key. Now, one-key feature about direct locators is that they are automatically retrying.
[3:22] That is, whenever we call locator.type or locator.press, Playwright will search for that particular locator at that point in time and will keep searching till it finds it or the test times out.
[3:34] For example, if you search for an input with the title equal searches, which is not something that exists on google.com, Playwright will keep searching for certain input to show up and only then will it try to press the enter key.
[3:46] Now because this particular locator does not exist, this test will eventually time out and we can see that in the test failure. Now traditional testing frameworks might have failed with an error like, cannot press enter on undefined, whereas Playwright fails with a much better error specifically stating that it cannot find this particular selector.
[4:04] As a side note, this test fails after 30 seconds because that is the default timeout that is set within playwright.config.ts. You are free to modify this time out to whatever value you want. For most people 30 seconds would be fine because Playwright tests are pretty done fast.
[4:21] Now, one final thing that we want to mention is that, when you are using the same locator again and again, feel free to move it into a local variable. For example, we can move this locator for the search input into a local variable called search input. Then use the same locator for the type as well as the press methods.
[4:37] Now, at runtime, whenever this type and this press are going to execute, that is the point in time at which Playwright will try to use the locator to find the particular element.