Playwright Python Sync and Async
Sync and Async API
Playwright for Python comes with two APIs that do exactly the same things: a sync API and an async API.
The sync API runs each line to the end before the next line starts, like normal Python code.
The async API uses Python's asyncio, with async and await, like the JavaScript API.
Both APIs can also be used without pytest, in plain Python scripts.
This chapter shows a script written with each one.
The Sync API
This script opens the todo list, adds a todo, prints two texts and saves a screenshot:
Example
first_script.py
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch()
page = browser.new_page()
page.goto("https://www.w3schools.com/playwright/practice/todo.html")
print(page.title())
page.get_by_placeholder("What needs to be done?").fill("Learn Playwright")
page.get_by_role("button", name="Add").click()
print(page.get_by_test_id("todo-count").text_content())
page.screenshot(path="todo.png")
browser.close()
Run it with Python:
Example
python first_script.py
Output:
Todo List | Playwright Practice
1 item left
The script also saved the file todo.png next to it.
Example Explained
from playwright.sync_api import sync_playwrightloads the sync APIwith sync_playwright() as p:starts Playwright, and stops it again when the block endsp.chromium.launch()starts a headless Chromium. Usep.firefoxorp.webkitfor the other browsersbrowser.new_page()opens a new tabpage.title()andtext_content()read text from the pagepage.screenshot(path="todo.png")saves a picture of the pagebrowser.close()closes the browser
In a test, the page fixture does the launching and closing for you.
In a script, you do it yourself.
Tip: Pass headless=False to launch() to see the browser window, and slow_mo=500 to slow it down.
The Async API
Here is the same script with the async API:
Example
first_script_async.py
import asyncio
from playwright.async_api import async_playwright
async def main():
async with async_playwright() as p:
browser = await p.chromium.launch()
page = await browser.new_page()
await page.goto("https://www.w3schools.com/playwright/practice/todo.html")
print(await page.title())
await page.get_by_placeholder("What needs to be done?").fill("Learn Playwright")
await page.get_by_role("button", name="Add").click()
print(await page.get_by_test_id("todo-count").text_content())
await page.screenshot(path="todo.png")
await browser.close()
asyncio.run(main())
Example
python first_script_async.py
Output:
Todo List | Playwright Practice
1 item left
The result is the same.
The differences are all in the Python around the Playwright calls:
- The import is from
playwright.async_api, and the function isasync_playwright - The code is inside an
async deffunction async withis used instead ofwith- Every call that talks to the browser has
awaitin front of it asyncio.run(main())starts an asyncio event loop (the part of asyncio that runs async code), and runs the function in it
Calls that only build a locator, like page.get_by_role(), do not need await.
The action on the locator, like .click(), does.
Sync or Async?
| Sync API | Async API | |
|---|---|---|
| Import | playwright.sync_api | playwright.async_api |
| Start Playwright | with sync_playwright() as p: | async with async_playwright() as p: |
| Browser calls | page.click(...) | await page.click(...) |
| Runs inside | Normal Python code | An asyncio event loop |
| Used by pytest-playwright | Yes | No |
Use the sync API for tests with pytest, and for most scripts.
It is shorter, and you cannot forget an await.
Use the async API when your program already uses asyncio, for example in an async web framework, or when you want to control many pages at the same time in one program.
Note: You cannot use the sync API inside a running asyncio event loop.
Playwright stops with the error "It looks like you are using Playwright Sync API inside the asyncio loop", and you should switch to the async API.
pytest Uses the Sync API
The page fixture from pytest-playwright is a sync Page.
That is why the tests in the Python First Test chapter import from playwright.sync_api and have no await.
Write your tests as normal def functions, not async def.
For async tests there is a separate plugin, pytest-playwright-asyncio.
The two plugins do not work together: pytest-playwright stops with an error if both are installed, so use only one of them.
This tutorial uses pytest-playwright.