Skip to content

Commit f38bf18

Browse files
AutomationPandaAutomationPanda
committed
Merge branch '0-initial-project' into 1-getting-started
2 parents 675fd38 + 5679646 commit f38bf18

File tree

1 file changed

+244
-7
lines changed

1 file changed

+244
-7
lines changed

‎README.md

Lines changed: 244 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,61 @@
11
# tau-playwright-workshop
22

3-
The Playwright Workshop for TAU: The Homecoming
3+
This repository contains the example code for the Playwright workshop
4+
for [TAU: The Homecoming](https://applitools.com/tau-homecoming/)
5+
on December 1, 2021.
6+
The workshop will be done in [Python](python.org).
47

8+
This README contains full instructions for the workshop.
9+
That way, you can still code along to learn Playwright even if you miss the main event!
510

6-
## Workshop outline
711

8-
1. Getting Started
12+
## Workshop details
13+
14+
This section contains information about the workshop.
15+
16+
17+
### Abstract
18+
19+
[Playwright](https://playwright.dev/python/)
20+
is a hot new browser automation tool from Microsoft.
21+
With bindings for .NET, Java, JavaScript, and Python, it’s a strong alternative to Selenium WebDriver for end-to-end web app testing.
22+
23+
This workshop will be an introduction to Playwright using [Python](python.org).
24+
We will automate a test scenario together that performs a [DuckDuckGo](https://duckduckgo.com/) search.
25+
As we code along the test together, we will learn:
26+
27+
* How to install and configure Playwright
28+
* How to integrate Playwright with [pytest](pytest.org), Python’s leading test framework
29+
* How to perform interactions through page objects
30+
* How to conveniently run different browsers, capture videos, and run tests in parallel
31+
32+
Come prepared with Python 3.7 or higher installed on your machine.
33+
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!
34+
35+
36+
### Prerequisites
37+
38+
To code along with this workshop, your machine must have Python 3.7 or higher.
39+
You should also have a decent Python editor like
40+
[Visual Studio Code](https://code.visualstudio.com/docs/languages/python)
41+
or [PyCharm](https://www.jetbrains.com/pycharm/).
42+
43+
The command line shown in examples below is [bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)).
44+
If you are using a different shell or a Windows command line, some commands may need to be different.
45+
46+
47+
### Agenda
48+
49+
This workshop has five main parts:
50+
51+
1. Getting started
952
1. What is Playwright?
1053
2. Our web search test
11-
3. Installations
12-
4. Test project setup
54+
3. Test project setup
1355
2. First steps with Playwright
56+
1. Raw Playwright calls
1457
3. Refactoring using page objects
58+
1. The search page
1559
4. Writing assertions
1660
1. Checking the search field
1761
2. Checking the result links
@@ -22,19 +66,212 @@ The Playwright Workshop for TAU: The Homecoming
2266
3. Running tests in parallel
2367

2468

25-
## Part 1: Getting started
69+
### Example code branches
70+
71+
Each part has a corresponding branch in this repository containing the part's example code.
72+
The branches allow you to check your progress at any point during the workshop.
73+
The branch names are:
74+
75+
| Part | Branch |
76+
| ------ | ------------------- |
77+
| Start | 0-initial-project |
78+
| Part 1 | 1-getting-started |
79+
| Part 2 | 2-raw-playwright |
80+
| Part 3 | 3-page-objects |
81+
| Part 4 | 4-assertions |
82+
| Part 5 | 5-playwright-tricks |
83+
84+
85+
## Workshop parts
86+
87+
This section contains the instructions for completing the workshop.
88+
You can code along with them either during the live workshop event or afterwards on your own.
89+
90+
91+
### Part 1: Getting started
92+
93+
94+
#### What is Playwright?
95+
96+
[Playwright](https://playwright.dev/python/) is a new library that can automate interactions with Chromium, Firefox, and WebKit browsers via a single API.
97+
It is an open source project developed by Microsoft.
98+
99+
Playwright is a fantastic alternative to [Selenium WebDriver](https://www.selenium.dev/) for web UI testing.
100+
Like Selenium WebDriver, Playwright has language bindings in multiple languages: Python, .NET, Java, and JavaScript.
101+
Playwright also refines many of the pain points in Selenium WebDriver.
102+
Some examples include:
103+
104+
* Playwright interactions automatically wait for elements to be ready.
105+
* Playwright can use one browser instance with multiple browser contexts for isolation instead of requiring multiple instances.
106+
* Playwright has device emulation for testing responsive web apps in mobile browsers.
107+
108+
For a more thorough list of advantages, check out
109+
[Why Playwright?](https://playwright.dev/python/docs/why-playwright/)
110+
from the docs.
111+
112+
113+
#### Our web search test
114+
115+
For this workshop, we will walk through one test scenario for DuckDuckGo searching.
116+
[DuckDuckGo](https://duckduckgo.com/) is a search engine like Google or Yahoo.
117+
118+
The steps for a basic DuckDuckGo search are:
119+
120+
```gherkin
121+
Given the DuckDuckGo home page is displayed
122+
When the user searches for a phrase
123+
Then the search result query is the phrase
124+
And the search result links pertain to the phrase
125+
And the search result title contains the phrase
126+
```
127+
128+
Go to [duckduckgo.com](https://duckduckgo.com/) and give this a try.
129+
You can use any search phrase you like.
130+
It is important to write a test *case* before writing test *code*.
131+
It is also important to try a test manually before attempting to automate it.
132+
133+
134+
#### Test project setup
135+
136+
Let's set up the test project!
137+
For this workshop, we will build a new project from the ground up.
138+
The GitHub repository should be used exclusively as a reference for example code.
139+
140+
Create a directory named `tau-playwright-workshop` for the project:
26141

27142
```bash
28143
$ mkdir tau-playwright-workshop
29144
$ cd tau-playwright-workshop
145+
```
146+
147+
Inside this project, create a [Python virtual environment](https://docs.python.org/3/tutorial/venv.html)
148+
using the [venv](https://docs.python.org/3/library/venv.html) module
149+
to manage dependency packages locally:
150+
151+
```bash
30152
$ python3 -m venv venv
31153
$ source venv/bin/activate
154+
```
155+
156+
Creating a new virtual environment for each Python project is a recommended practice.
157+
This command will create a subdirectory named `venv` that holds all virtual environment files, including dependency packages.
158+
After creating a virtual environment, you must "activate" it to use it using the `source` command shown above.
159+
You can tell if a virtual environment is active if its name appears in the bash prompt.
160+
161+
*A note about Python commands:*
162+
Python has two incompatible major versions: 2 and 3.
163+
Although Python 2 end-of-life was January 1, 2020, many machines still run it.
164+
For example, macOS comes bundled with Python 2.7.18.
165+
Sometimes, the `python` executable may point to Python 2 instead of 3.
166+
To be precise about versions and executables, we will use the `python3` and `pip3` commands explicitly in this workshop.
167+
168+
Let's add some Python packages to our new virtual environment:
169+
170+
```bash
32171
$ pip3 install playwright
33172
$ pip3 install pytest
173+
$ pip3 install pytest-playwright
174+
```
175+
176+
By itself, Playwright is simply a library for browser automation.
177+
We need a test framework like pytest if we want to automate tests.
178+
The [`pytest-playwright`](https://playwright.dev/python/docs/test-runners)
179+
is a pytest plugin developed by the Playwright team that simplifies Playwright integration.
180+
181+
You can check all installed packages using `pip3 freeze`.
182+
They should look something like this:
183+
184+
```bash
34185
$ pip3 freeze
186+
attrs==21.2.0
187+
greenlet==1.1.2
188+
iniconfig==1.1.1
189+
packaging==21.3
190+
playwright==1.17.0
191+
pluggy==1.0.0
192+
py==1.11.0
193+
pyee==8.2.2
194+
pyparsing==3.0.6
195+
pytest==6.2.5
196+
toml==0.10.2
197+
websockets==10.1
198+
```
199+
200+
Notice that pip fetches dependencies of dependencies.
201+
It is customary for Python projects to store this list of dependencies in a file named `requirements.txt`.
202+
203+
After the Python packages are installed, we need to install the browsers for Playwright.
204+
The `playwright install` command installs the latest versions of the three browsers that Playwright supports:
205+
Chromium, Firefox, and WebKit:
206+
207+
```bash
35208
$ playwright install
36209
```
37210

38-
* Explain virtual environments
211+
By default, pytest with the Playwright plugin will run headless Chromium.
212+
We will show how to run against other browsers in Part 5.
213+
214+
Finally, let's create a test function stub.
215+
By Python conventions, all tests should be located under a `tests` directory.
216+
Create a `tests` directory, and inside, create a file named `test_search.py`:
217+
218+
```bash
219+
$ mkdir tests
220+
$ touch tests/test_search.py
221+
```
222+
223+
Add the following code to `tests/test_search.py`:
224+
225+
```python
226+
def test_basic_duckduckgo_search():
227+
# Given the DuckDuckGo home page is displayed
228+
# When the user searches for a phrase
229+
# Then the search result query is the phrase
230+
# And the search result links pertain to the phrase
231+
# And the search result title contains the phrase
232+
pass
233+
```
234+
235+
The `test_basic_duckduckgo_search` is merely a stub, but it establishes good practices:
236+
237+
* It has a clear name.
238+
* It defines the behavior to test step-by-step in its comments.
239+
* It can be run immediately.
240+
241+
The `pass` statement at the end is just a no-op.
242+
243+
Remember, write test *cases* before you write test *code*.
244+
245+
Before continuing, run this test to make sure everything is set up correctly:
246+
247+
```bash
248+
$ python3 -m pytest tests
249+
```
250+
251+
pytest should discover, run, and pass the single test case under the `tests` directory.
252+
253+
*A note about the pytest command:*
254+
Many online articles and examples use the `pytest` command directly to run tests, like this: `pytest tests`.
255+
Unfortunately, this version of the command does **not** add the current directory to the Python path.
256+
If your tests reference anything outside of their test modules, then the command will fail.
257+
Therefore, I always recommend running the full `python3 -m pytest tests` command.
258+
259+
260+
### Part 2: First steps with Playwright
261+
262+
TBD
263+
264+
265+
### Part 3: Refactoring using page objects
266+
267+
TBD
268+
269+
270+
### Part 4: Writing assertions
271+
272+
TBD
273+
39274

275+
### Part 5: Nifty Playwright tricks
40276

277+
TBD

0 commit comments

Comments
 (0)