Merge branch '5-playwright-tricks' into 6-api-testing

Author: AutomationPanda

pages/result.py

@@ -3,26 +3,22 @@
 the page object for the DuckDuckGo result page.
 """
 
+from playwright.sync_api import Page
+from typing import List
+
+
 class DuckDuckGoResultPage:
 
-    RESULT_LINKS = '.result__title a.result__a'
-    SEARCH_INPUT = '#search_form_input'
-    
-    def __init__(self, page):
+    def __init__(self, page: Page) -> None:
         self.page = page
+        self.result_links = page.locator('.result__title a.result__a')
+        self.search_input = page.locator('#search_form_input')
 
-    def result_link_titles(self):
-        self.page.locator(f'{self.RESULT_LINKS} >> nth=4').wait_for()
-        titles = self.page.locator(self.RESULT_LINKS).all_text_contents()
-        return titles
+    def result_link_titles(self) -> List[str]:
+        self.result_links.nth(4).wait_for()
+        return self.result_links.all_text_contents()
 
-    def result_link_titles_contain_phrase(self, phrase, minimum=1):
+    def result_link_titles_contain_phrase(self, phrase: str, minimum: int = 1) -> bool:
         titles = self.result_link_titles()
         matches = [t for t in titles if phrase.lower() in t.lower()]
         return len(matches) >= minimum
-
-    def search_input_value(self):
-        return self.page.input_value(self.SEARCH_INPUT)
-    
-    def title(self):
-        return self.page.title()

pages/search.py

@@ -3,19 +3,21 @@
 the page object for the DuckDuckGo search page.
 """
 
-class DuckDuckGoSearchPage:
+from playwright.sync_api import Page
+
 
-    SEARCH_BUTTON = '#search_button_homepage'
-    SEARCH_INPUT = '#search_form_input_homepage'
+class DuckDuckGoSearchPage:
 
     URL = 'https://www.duckduckgo.com'
 
-    def __init__(self, page):
+    def __init__(self, page: Page) -> None:
         self.page = page
+        self.search_button = page.locator('#search_button_homepage')
+        self.search_input = page.locator('#search_form_input_homepage')
 
-    def load(self):
+    def load(self) -> None:
         self.page.goto(self.URL)
 
-    def search(self, phrase):
-        self.page.fill(self.SEARCH_INPUT, phrase)
-        self.page.click(self.SEARCH_BUTTON)
+    def search(self, phrase: str) -> None:
+        self.search_input.fill(phrase)
+        self.search_button.click()

tests/conftest.py

@@ -16,15 +16,17 @@
 
 from pages.result import DuckDuckGoResultPage
 from pages.search import DuckDuckGoSearchPage
+from playwright.sync_api import Page
+
 
 
 @pytest.fixture
-def result_page(page):
+def result_page(page: Page) -> DuckDuckGoResultPage:
     return DuckDuckGoResultPage(page)
 
 
 @pytest.fixture
-def search_page(page):
+def search_page(page: Page) -> DuckDuckGoSearchPage:
     return DuckDuckGoSearchPage(page)
 
 

tests/test_search.py

@@ -4,6 +4,10 @@
 
 import pytest
 
+from pages.result import DuckDuckGoResultPage
+from pages.search import DuckDuckGoSearchPage
+from playwright.sync_api import expect, Page
+
 
 ANIMALS = [
     'panda',
@@ -20,19 +24,23 @@
 
 
 @pytest.mark.parametrize('phrase', ANIMALS)
-def test_basic_duckduckgo_search(search_page, result_page, phrase):
-
+def test_basic_duckduckgo_search(
+    phrase: str,
+    page: Page,
+    search_page: DuckDuckGoSearchPage,
+    result_page: DuckDuckGoResultPage) -> None:
+    
     # Given the DuckDuckGo home page is displayed
     search_page.load()
 
     # When the user searches for a phrase
     search_page.search(phrase)
 
     # Then the search result query is the phrase
-    assert phrase == result_page.search_input_value()
+    expect(result_page.search_input).to_have_value(phrase)
 
     # And the search result links pertain to the phrase
     assert result_page.result_link_titles_contain_phrase(phrase)
 
     # And the search result title contains the phrase
-    assert phrase in result_page.title()
+    expect(page).to_have_title(f'{phrase} at DuckDuckGo')

tutorial/1-getting-started.md

@@ -162,7 +162,7 @@ $ touch tests/test_search.py
 Add the following code to `tests/test_search.py`:
 
 ```python
-def test_basic_duckduckgo_search():
+def test_basic_duckduckgo_search() -> None:
     # Given the DuckDuckGo home page is displayed
     # When the user searches for a phrase
     # Then the search result query is the phrase

tutorial/2-first-steps.md

@@ -58,16 +58,22 @@ You do not need to explicitly close the browser.
 > Asynchronous calls could be useful for other types of automation, such as web scraping.
 
 Let's update our test stub to call the `page` fixture.
-In `tests/test_search.py`, change the test function signature from this:
+In `tests/test_search.py`, add the following import statement:
 
 ```python
-def test_basic_duckduckgo_search():
+from playwright.sync_api import Page
+```
+
+Then, change the test function signature from this:
+
+```python
+def test_basic_duckduckgo_search() -> None:
 ```
 
 To this:
 
 ```python
-def test_basic_duckduckgo_search(page):
+def test_basic_duckduckgo_search(page: Page) -> None:
 ```
 
 Now the test has access to a fresh page in a new browser context.
@@ -172,22 +178,32 @@ Here's the inspection panel for the search input element:
 Thankfully, this element has an ID.
 We can use the selector `#search_form_input_homepage` to uniquely identify this element.
 
-To enter text into this input element, we must use Playwright's
-[`fill`](https://playwright.dev/python/docs/api/class-page#page-fill) method.
+To interact with elements with Playwright, we must use [locators](https://playwright.dev/python/docs/locators).
+The [Locator](https://playwright.dev/python/docs/next/api/class-locator) class
+takes in a selector and produces an object that can interact with the target element.
+
+For example, to enter text into this input element, we must use `Locator`'s
+[`fill`](https://playwright.dev/python/docs/next/api/class-locator#locator-fill) method.
 Append the following line to the test case:
 
 ```python
-    page.fill('#search_form_input_homepage', 'panda')
+    page.locator('#search_form_input_homepage').fill('panda')
 ```
 
 > Since `search_form_input_homepage` is an ID, we could also use Playwright's
 > [ID attribute selector](https://playwright.dev/python/docs/selectors#id-data-testid-data-test-id-data-test-selectors):
 >  
-> `page.fill('id=search_form_input_homepage', 'panda')`
+> `page.locator('id=search_form_input_homepage').fill('panda')`
 
-Using Selenium WebDriver, we would need to locate the element and then send the interaction to it.
-However, in Playwright, these two parts are combined into a single call.
-Furthermore, Playwright waits for the target element to be visible and editable before it attempts to enter the text.
+> Playwright's `Page` class also provides methods for element interactions like this:
+>  
+> `page.fill('#search_form_input_homepage', 'panda')`
+>  
+> However, using locators is recommended over direct page calls.
+> Locators use "strict" mode - a locator raises an exception if its selector finds more than one element.
+> Locators are also more reusable, especially when using page object classes.
+
+Playwright waits for the target element to be visible and editable before it attempts to enter the text.
 We are arbitrarily using the phrase `'panda'` as our search phrase because, well, why not?
 
 Let's handle the second part of the interaction: clicking the search button.
@@ -198,11 +214,11 @@ Here's the inspection panel for the search button:
 This element also has an ID: `#search_button_homepage`. Nice!
 
 To click an element, we must use Playwright's
-[`click`](https://playwright.dev/python/docs/api/class-page#page-click) method.
+[`click`](https://playwright.dev/python/docs/next/api/class-locator#locator-click) method.
 Append the following line to the test case:
 
 ```python
-    page.click('#search_button_homepage')
+    page.locator('#search_button_homepage').click()
 ```
 
 Again, Playwright is nice and concise.
@@ -211,14 +227,15 @@ The `click` method waits for the target element to be ready to receive clicks, t
 Our test case should now look like this:
 
 ```python
-def test_basic_duckduckgo_search(page):
+from playwright.sync_api import Page
 
+def test_basic_duckduckgo_search(page: Page) -> None:
     # Given the DuckDuckGo home page is displayed
     page.goto('https://www.duckduckgo.com')
 
     # When the user searches for a phrase
-    page.fill('#search_form_input_homepage', 'panda')
-    page.click('#search_button_homepage')
+    page.locator('#search_form_input_homepage').fill('panda')
+    page.locator('#search_button_homepage').click()
 
     # Then the search result query is the phrase
     # And the search result links pertain to the phrase
@@ -231,5 +248,7 @@ Now, you should see the test actually perform the search!
 
 Navigation, input filling, and clicking are only three of many page interactions you can do with Playwright.
 Anything a user can do on a web page, Playwright can do as well.
-Check out the Playwright [Page](https://playwright.dev/python/docs/api/class-page) API to see *all* methods and attributes.
+Check out the Playwright [Page](https://playwright.dev/python/docs/api/class-page)
+and [Locator](https://playwright.dev/python/docs/next/api/class-locator) classes
+to see *all* methods and attributes.
 We will use more of these calls in the next tutorial parts.