Merge branch '4-page-objects' into 5-playwright-tricks

Author: AutomationPanda

README.md

@@ -1,57 +1,66 @@
-![Workshop card](workshop/images/workshop-card.png)
+![Playwright banner](tutorial/images/playwright-banner.jpeg)
 
-# tau-playwright-workshop
 
-This repository contains the instructions and example code for the Playwright workshop
-for [TAU: The Homecoming](https://applitools.com/tau-homecoming/)
-on December 1, 2021.
-The workshop will be done in [Python](https://www.python.org/).
+# Tutorial: Web Testing with Playwright in Python
 
 
-## Instructions
+## Abstract
 
-Please try to attend the workshop *live* on the day of the event.
-However, if you cannot make it, never fear!
-**You can still take the workshop as a self-guided tutorial.**
-Start by reading this README.
-Then, follow the guides in the `workshop` folder.
-Each part of the workshop has a `workshop` guide with full instructions.
-Feel free to open issues against this repository if you have any trouble completing the workshop independently.
+Everybody gets frustrated when web apps are broken,
+but testing them thoroughly doesn't need to be a chore.
+[Playwright](https://playwright.dev/python/),
+a new open-source browser automation tool from Microsoft,
+makes testing web apps fun!
+Playwright outperforms other browser automation with a slew of nifty features
+like automatic waiting, mobile emulation, and network interception.
+Plus, with isolated browser contexts,
+Playwright tests can set up *much* faster than traditional Web UI tests.
 
+In this tutorial, we will build a [Python](https://www.python.org/)
+test automation project from the ground up using Playwright.
+We will automate web search engine tests together step-by-step
+using Playwright for interactions and pytest for execution.
+We'll also explore Playwright tricks
+like cross-browser testing, capturing videos, and even running tests in parallel!
+By the end of this tutorial, you'll be empowered to test modern web apps with modern web test tools.
+You'll also have an example project to be the foundation for your future tests.
 
-## Abstract
 
-[Playwright](https://playwright.dev/python/)
-is a hot new browser automation tool from Microsoft.
-With bindings for .NET, Java, JavaScript, and Python, it’s a strong alternative to Selenium WebDriver for end-to-end web app testing.
+## What is Playwright?
 
-This workshop will be an introduction to Playwright using [Python](https://www.python.org/).
-We will automate a test scenario together that performs a [DuckDuckGo](https://duckduckgo.com/) search.
-As we code along the test together, we will learn:
+Playwright is a fairly new test automation framework from Microsoft.
+It is open source, and it has bindings in TypeScript/JavaScript, Python, .NET, and Java.
+Some of the nice features Playwright offers include:
 
-* How to install and configure Playwright
-* How to integrate Playwright with [pytest](https://docs.pytest.org/), Python’s leading test framework
-* How to perform interactions through page objects
-* How to conveniently run different browsers, capture videos, and run tests in parallel
+* concise, readable calls
+* easy out-of-the-box setup
+* very fast execution times (compared to other browser automation tools)
+* cross-browser and mobile emulation support
+* automatic waiting
+* built-in API calls
+* screenshots and video capture
 
-Come prepared with Python 3.7 or higher installed on your machine.
-By the end of the workshop, you will have a solid foundation in Playwright as well as a Python project you can extend with new tests!
+Microsoft is actively developing Playwright,
+so new features are coming all the time!
 
 
-## Prerequisites
+## Tutorial Instructions
 
-To code along with this workshop, your machine must have Python 3.7 or higher.
-You should also have a decent Python editor like
-[Visual Studio Code](https://code.visualstudio.com/docs/languages/python)
-or [PyCharm](https://www.jetbrains.com/pycharm/).
+You can take this tutorial independently by following the instructions
+in this `README` and in the [`tutorial`](tutorial) folder.
+Feel free to open issues against this repository if you have any trouble completing the tutorial independently.
 
-The command line shown in examples below is [bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)).
-If you are using a different shell or a Windows command line, some commands may need to be different.
+I also have given (or will be giving) this tutorial as a live workshop at the following events:
 
+* [TAU: The Homecoming](https://applitools.com/on-demand-videos/tau-the-homecoming-2021/) (December 1, 2021)
+* [Python Web Conference 2022](https://2022.pythonwebconf.com/tutorials/end-to-end-testing-with-playwright) (March 22, 2021)
+* [STAREast 2022](https://stareast.techwell.com/program/tutorials/web-ui-testing-playwright-python-stareast-2022) (April 26, 2022)
+* [PyCon US 2022](https://us.pycon.org/2022/schedule/presentation/35/) (April 28, 2022)
 
-## Agenda
 
-This workshop has five main parts, each with three sections:
+## Outline
+
+This tutorial has five main parts, each with three sections:
 
 1. Getting started
    1. What is Playwright?
@@ -75,10 +84,25 @@ This workshop has five main parts, each with three sections:
    3. Running tests in parallel
 
 
+## Prerequisites
+
+You must have basic Python programming skills to complete this tutorial.
+If you are new to Python, check out the free
+[Python Programming](https://testautomationu.applitools.com/python-tutorial/) course
+on Test Automation University.
+
+Your machine must also have Python 3.7 or higher installed.
+You can download the latest version of Python from [Python.org](https://www.python.org/).
+
+You should also have a decent Python editor like
+[Visual Studio Code](https://code.visualstudio.com/docs/languages/python)
+or [PyCharm](https://www.jetbrains.com/pycharm/).
+
+
 ## Example code branches
 
-Each workshop part has a corresponding branch in this repository containing the part's example code and `workshop` instructions.
-The branches allow you to check your progress at any point during the workshop.
+Each tutorial part has a corresponding branch in this repository containing the part's example code and `tutorial` instructions.
+The branches allow you to check your progress at any point during the tutorial.
 The branch names are:
 
 | Part     | Branch              |

requirements.txt

@@ -6,19 +6,20 @@ greenlet==1.1.2
 idna==3.3
 iniconfig==1.1.1
 packaging==21.3
-playwright==1.17.0
+playwright==1.19.1
 pluggy==1.0.0
 py==1.11.0
-pyee==8.2.2
+pyee==8.1.0
 pyparsing==3.0.6
-pytest==6.2.5
+pytest==7.0.1
 pytest-base-url==1.4.2
-pytest-forked==1.3.0
-pytest-playwright==0.2.2
-pytest-xdist==2.4.0
+pytest-forked==1.4.0
+pytest-playwright==0.2.3
+pytest-xdist==2.5.0
 python-slugify==5.0.2
 requests==2.26.0
 text-unidecode==1.3
 toml==0.10.2
+tomli==2.0.1
 urllib3==1.26.7
 websockets==10.1

workshop/1-getting-started.md renamed to tutorial/1-getting-started.md

@@ -1,6 +1,6 @@
 # Part 1: Getting started
 
-Part 1 of the workshop explains how to set up a Python test automation project with pytest and Playwright.
+Part 1 of the tutorial explains how to set up a Python test automation project with pytest and Playwright.
 
 
 ## What is Playwright?
@@ -24,7 +24,7 @@ from the docs.
 
 ## Our web search test
 
-For this workshop, we will walk through one test scenario for DuckDuckGo searching.
+For this tutorial, we will walk through one test scenario for DuckDuckGo searching.
 [DuckDuckGo](https://duckduckgo.com/) is a search engine like Google or Yahoo.
 
 The steps for a basic DuckDuckGo search are:
@@ -46,14 +46,14 @@ It is also important to try a test manually before attempting to automate it.
 ## Test project setup
 
 Let's set up the test project!
-For this workshop, we will build a new project from the ground up.
+For this tutorial, we will build a new project from the ground up.
 The GitHub repository should be used exclusively as a reference for example code.
 
-Create a directory named `tau-playwright-workshop` for the project:
+Create a directory named `playwright-python-tutorial` for the project:
 
 ```bash
-$ mkdir tau-playwright-workshop
-$ cd tau-playwright-workshop
+$ mkdir playwright-python-tutorial
+$ cd playwright-python-tutorial
 ```
 
 Inside this project, create a [Python virtual environment](https://docs.python.org/3/tutorial/venv.html)
@@ -72,7 +72,7 @@ Python has two incompatible major versions: 2 and 3.
 Although Python 2 end-of-life was January 1, 2020, many machines still run it.
 For example, macOS comes bundled with Python 2.7.18.
 Sometimes, the `python` executable may point to Python 2 instead of 3.
-To be precise about versions and executables, we will use the `python3` and `pip3` commands explicitly in this workshop.
+To be precise about versions and executables, we will use the `python3` and `pip3` commands explicitly in this tutorial.
 
 After creating a virtual environment, you must "activate" it.
 On macOS or Linux, use the following command:
@@ -97,6 +97,11 @@ $ pip3 install pytest
 $ pip3 install pytest-playwright
 ```
 
+> If you want to run the tests from this repository instead of creating a fresh project,
+> install the dependencies using this command:
+>  
+> `$ pip3 install -r requirements.txt`
+
 By itself, Playwright is simply a library for browser automation.
 We need a test framework like pytest if we want to automate tests.
 The [`pytest-playwright`](https://playwright.dev/python/docs/test-runners)
@@ -114,18 +119,19 @@ greenlet==1.1.2
 idna==3.3
 iniconfig==1.1.1
 packaging==21.3
-playwright==1.17.0
+playwright==1.19.1
 pluggy==1.0.0
 py==1.11.0
-pyee==8.2.2
+pyee==8.1.0
 pyparsing==3.0.6
-pytest==6.2.5
+pytest==7.0.1
 pytest-base-url==1.4.2
-pytest-playwright==0.2.2
+pytest-playwright==0.2.3
 python-slugify==5.0.2
 requests==2.26.0
 text-unidecode==1.3
 toml==0.10.2
+tomli==2.0.1
 urllib3==1.26.7
 websockets==10.1
 ```

workshop/2-first-steps.md renamed to tutorial/2-first-steps.md

@@ -1,6 +1,6 @@
 # Part 2: First steps with Playwright
 
-Part 2 of the workshop shows how to take your first steps with Playwright calls.
+Part 2 of the tutorial shows how to take your first steps with Playwright calls.
 It will explain browsers, contexts, and pages.
 It will also cover basic Playwright API calls.
 
@@ -136,14 +136,15 @@ Out of the box, Playwright supports the following types of selectors:
 * N-th element
 * React
 * Vue
+* ID attributes
 
 Text and CSS selectors also pierce the Shadow DOM by default!
 
 In general, you should keep selectors as simple as possible.
 Try to stick to text, IDs, or CSS selectors.
 Use more complicated selectors only as necessary.
 
-This workshop will not cover recommended practices for element selectors deeply.
+This tutorial will not cover recommended practices for element selectors deeply.
 If you want to learn more about selectors,
 read the [Element selectors](https://playwright.dev/python/docs/selectors) page in the Playwright docs,
 or take the [Web Element Locator Strategies](https://testautomationu.applitools.com/web-element-locator-strategies/) course
@@ -175,6 +176,11 @@ Append the following line to the test case:
     page.fill('#search_form_input_homepage', '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')`
+
 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.
@@ -222,4 +228,4 @@ 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.
-We will use more of these calls in the next workshop parts.
+We will use more of these calls in the next tutorial parts.

workshop/3-assertions.md renamed to tutorial/3-assertions.md

@@ -1,6 +1,6 @@
 # Part 3: Writing assertions
 
-Part 3 of the workshop focuses on making assertions about the result page after performing a search.
+Part 3 of the tutorial focuses on making assertions about the result page after performing a search.
 Waiting becomes a much bigger concern for these steps, but Playwright makes it easy.
 
 
@@ -245,8 +245,13 @@ Rerun the test again to make sure it works.
 If it does, congrats!
 You have just completed a full test case in Python using Playwright with pytest.
 
+Playwright's [`Page`](https://playwright.dev/python/docs/api/class-page) class
+provides several methods for interacting with pages and getting state from them.
+Read the docs to familiarize yourself with them.
+`Page` provides methods to interact with *every* type of web element.
+
 Notice how concise this code is.
 Unfortunately, it's not very reusable.
 If other tests needed to perform DuckDuckGo searches,
 they would duplicate similar calls.
-In the next workshop part, we will refactor this test using page objects to make the code more reusable and extendable.
+In the next tutorial part, we will refactor this test using page objects to make the code more reusable and extendable.

workshop/4-page-objects.md renamed to tutorial/4-page-objects.md

@@ -29,7 +29,7 @@ Create a new directory named `pages`, and inside it, create blank files with the
 Your project's directory layout should look like this:
 
 ```
-tau-playwright-workshop
+playwright-python-tutorial
 ├── pages
 │   ├── __init__.py
 │   ├── search.py
@@ -77,7 +77,7 @@ Let's also add the DuckDuckGo URL:
 
 *(Warning:
 Base URLs should typically be passed into automation code as an input, not hard-coded in a page object.
-We are doing this here as a matter of simplicity for this workshop.)*
+We are doing this here as a matter of simplicity for this tutorial.)*
 
 Next, let's handle dependency injection for the browser automator.
 Since each test will have its own Playwright page, we should inject that page.
@@ -90,7 +90,7 @@ Add the following initializer method to the class:
 ```
 
 The `__init__` method is essentially a constructor for Python classes
-(but with a bit of nuance that doesn't matter for this workshop).
+(but with a bit of nuance that doesn't matter for this tutorial).
 It has one argument named `page` for the Playwright page,
 which it stores as an instance variable (via `self`).
 
@@ -335,7 +335,7 @@ Create a new file at `tests/conftest.py`.
 The new project directory layout should look like this:
 
 ```
-tau-playwright-workshop
+playwright-python-tutorial
 ├── pages
 │   ├── __init__.py
 │   ├── search.py