# litestar-playwright
<!-- TODO: Make it work, make it right, make it fast. -->
[](https://github.com/hasansezertasan/litestar_playwright/actions/workflows/ci.yml)
[](https://pypi.org/project/litestar_playwright)
[](https://pypi.org/project/litestar_playwright)
[](https://opensource.org/licenses/MIT)
[](https://github.com/hasansezertasan/litestar_playwright)
[](http://mypy-lang.org/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/hasansezertasan/litestar_playwright/releases/)
[](https://pepy.tech/project/litestar_playwright)
[](https://pepy.tech/project/litestar_playwright)
[](https://pepy.tech/project/litestar_playwright)
Playwright integration for Litestar.
---
## Table of Contents
<!--toc:start-->
- [litestar-playwright](#litestar-playwright)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Usage](#usage)
- [Accessing Browser Instances](#accessing-browser-instances)
- [Web Scraping Example](#web-scraping-example)
- [Multiple Playwright Plugins Example](#multiple-playwright-plugins-example)
- [Support :heart:](#support-heart)
- [Author :person_with_crown:](#author-personwithcrown)
- [Contributing :heart:](#contributing-heart)
- [Tasks](#tasks)
- [`install`](#install)
- [`style`](#style)
- [`ci`](#ci)
- [`run-simple`](#run-simple)
- [`run-multiple-plugins`](#run-multiple-plugins)
- [License](#license)
- [Changelog :memo:](#changelog-memo)
<!--toc:end-->
## Features
- 🎭 **Browser Management**: Manage Playwright browser instances
- 🔧 **Dependency Injection**: Automatic injection of browser instances into route handlers
- ⚡ **Async Support**: Full async/await support for all operations
## Installation
```sh
uv add litestar-playwright
```
## Quick Start
```python
from litestar import Litestar
from litestar_playwright.config import PlaywrightConfig
from litestar_playwright.plugin import PlaywrightPlugin
# Create the plugin with configuration
playwright_plugin = PlaywrightPlugin(
config=PlaywrightConfig(
browser_type="chromium", # or "firefox", "webkit"
headless=False, # Show browser windows
)
)
# Add to your Litestar app
app = Litestar(plugins=[playwright_plugin])
```
## Configuration
The `PlaywrightConfig` class provides several configuration options:
```python
@dataclass
class PlaywrightConfig:
headless: bool = True
"""Whether to run browsers in headless mode."""
browser_type: str = "chromium"
"""Type of browser to use (chromium, firefox, webkit)."""
playwright_app_state_key: str = "playwright_browser"
"""Key used to store the browser instance in app state."""
```
## Usage
### Accessing Browser Instances
The plugin automatically injects browser instances into your route handlers:
```python
from litestar import get
from playwright.async_api import Browser
@get("/my-route")
async def my_route(playwright_browser: Browser) -> str:
# Create a new context
context = await playwright_browser.new_context()
# Create a new page
page = await context.new_page()
# Navigate to a URL
await page.goto("https://example.com")
return "Page loaded!"
```
### Web Scraping Example
Here's a complete example of web scraping with the plugin:
```python
from litestar import get
from playwright.async_api import Browser
@get("/scrape")
async def scrape_website(playwright_browser: Browser) -> dict:
# Create a new context
context = await playwright_browser.new_context()
try:
# Create a new page
page = await context.new_page()
# Navigate to a website
await page.goto("https://example.com")
# Extract information
title = await page.title()
content = await page.content()
return {
"title": title,
"content_length": len(content)
}
finally:
# Always clean up
await context.close()
```
### Multiple Playwright Plugins Example
You can use multiple Playwright plugins in a single application for different use cases:
```python
from litestar import Litestar, get
from playwright.async_api import Browser
from litestar_playwright.config import PlaywrightConfig
from litestar_playwright.plugin import PlaywrightPlugin
# Create different configurations for various browsers
chrome_config = PlaywrightConfig(
browser_type="chromium",
headless=False,
launch_kwargs={"args": ["--no-sandbox"]},
playwright_browser_instance_state_key="chrome_browser",
)
firefox_config = PlaywrightConfig(
browser_type="firefox",
headless=False,
playwright_browser_instance_state_key="firefox_browser",
)
# Route handlers can inject specific browser instances
@get("/chrome-info")
async def chrome_info(chrome_browser: Browser) -> dict:
return {"browser": chrome_browser.browser_type.name}
@get("/firefox-info")
async def firefox_info(firefox_browser: Browser) -> dict:
return {"browser": firefox_browser.browser_type.name}
# Use multiple plugins in your app
app = Litestar(
plugins=[
PlaywrightPlugin(config=chrome_config),
PlaywrightPlugin(config=firefox_config),
],
route_handlers=[chrome_info, firefox_info],
)
```
This approach is useful for:
- **Cross-browser testing**: Test your application across different browsers
- **Specialized workflows**: Use different browsers for different tasks
- **CI/CD scenarios**: Run headless browsers for automated testing
- **Performance testing**: Compare behavior across browser engines
## Support :heart:
If you have any questions or need help, feel free to open an issue on the [GitHub repository][litestar_playwright].
## Author :person_with_crown:
This project is maintained by [Hasan Sezer Taşan][author], It's me :wave:
## Contributing :heart:
Any contributions are welcome! Please follow the [Contributing Guidelines](./CONTRIBUTING.md) to contribute to this project.
## Tasks
Clone the repository and cd into the project directory:
```sh
git clone https://github.com/hasansezertasan/litestar_playwright
cd litestar_playwright
```
The commands below can also be executed using the [xc task runner](https://xcfile.dev/), which combines the usage instructions with the actual commands. Simply run `xc`, it will pop up an interactive menu with all available tasks.
### `install`
Install the dependencies:
```sh
uv sync
uv run playwright install
```
### `style`
Run the style checks:
```sh
uv run --locked tox run -e style
```
### `ci`
Run the CI pipeline:
```sh
uv run --locked tox run
```
### `run-simple`
Run the simple example:
```sh
uv run python examples/simple.py
```
### `run-multiple-plugins`
Run the multiple plugins example:
```sh
uv run python examples/multiple_plugins.py
```
## License
`litestar-playwright` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
## Changelog :memo:
For a detailed list of changes, please refer to the [CHANGELOG](./CHANGELOG.md).
<!-- Refs -->
[author]: https://github.com/hasansezertasan
[litestar_playwright]: https://github.com/hasansezertasan/litestar-playwright
Raw data
{
"_id": null,
"home_page": null,
"name": "litestar-playwright",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Hasan Sezer Ta\u015fan <hasansezertasan@gmail.com>",
"keywords": "automation, browser, litestar, litestar-extension, litestar-playwright, litestar-plugin, playwright, testing",
"author": null,
"author_email": "Hasan Sezer Ta\u015fan <hasansezertasan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d0/7b/a4e8c0121dedc50839d0e1a6d7398114ffa0888e3519e8e1aa8f3d13a1fe/litestar_playwright-0.1.0.tar.gz",
"platform": null,
"description": "# litestar-playwright\n\n<!-- TODO: Make it work, make it right, make it fast. -->\n\n[](https://github.com/hasansezertasan/litestar_playwright/actions/workflows/ci.yml)\n[](https://pypi.org/project/litestar_playwright)\n[](https://pypi.org/project/litestar_playwright)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/hasansezertasan/litestar_playwright)\n\n[](http://mypy-lang.org/)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/hasansezertasan/litestar_playwright/releases/)\n\n[](https://pepy.tech/project/litestar_playwright)\n[](https://pepy.tech/project/litestar_playwright)\n[](https://pepy.tech/project/litestar_playwright)\n\nPlaywright integration for Litestar.\n\n---\n\n## Table of Contents\n\n<!--toc:start-->\n\n- [litestar-playwright](#litestar-playwright)\n - [Table of Contents](#table-of-contents)\n - [Features](#features)\n - [Installation](#installation)\n - [Quick Start](#quick-start)\n - [Configuration](#configuration)\n - [Usage](#usage)\n - [Accessing Browser Instances](#accessing-browser-instances)\n - [Web Scraping Example](#web-scraping-example)\n - [Multiple Playwright Plugins Example](#multiple-playwright-plugins-example)\n - [Support :heart:](#support-heart)\n - [Author :person_with_crown:](#author-personwithcrown)\n - [Contributing :heart:](#contributing-heart)\n - [Tasks](#tasks)\n - [`install`](#install)\n - [`style`](#style)\n - [`ci`](#ci)\n - [`run-simple`](#run-simple)\n - [`run-multiple-plugins`](#run-multiple-plugins)\n - [License](#license)\n - [Changelog :memo:](#changelog-memo)\n\n<!--toc:end-->\n\n## Features\n\n- \ud83c\udfad **Browser Management**: Manage Playwright browser instances\n- \ud83d\udd27 **Dependency Injection**: Automatic injection of browser instances into route handlers\n- \u26a1 **Async Support**: Full async/await support for all operations\n\n## Installation\n\n```sh\nuv add litestar-playwright\n```\n\n## Quick Start\n\n```python\nfrom litestar import Litestar\nfrom litestar_playwright.config import PlaywrightConfig\nfrom litestar_playwright.plugin import PlaywrightPlugin\n\n# Create the plugin with configuration\nplaywright_plugin = PlaywrightPlugin(\n config=PlaywrightConfig(\n browser_type=\"chromium\", # or \"firefox\", \"webkit\"\n headless=False, # Show browser windows\n )\n)\n\n# Add to your Litestar app\napp = Litestar(plugins=[playwright_plugin])\n```\n\n## Configuration\n\nThe `PlaywrightConfig` class provides several configuration options:\n\n```python\n@dataclass\nclass PlaywrightConfig:\n headless: bool = True\n \"\"\"Whether to run browsers in headless mode.\"\"\"\n\n browser_type: str = \"chromium\"\n \"\"\"Type of browser to use (chromium, firefox, webkit).\"\"\"\n\n playwright_app_state_key: str = \"playwright_browser\"\n \"\"\"Key used to store the browser instance in app state.\"\"\"\n```\n\n## Usage\n\n### Accessing Browser Instances\n\nThe plugin automatically injects browser instances into your route handlers:\n\n```python\nfrom litestar import get\nfrom playwright.async_api import Browser\n\n@get(\"/my-route\")\nasync def my_route(playwright_browser: Browser) -> str:\n # Create a new context\n context = await playwright_browser.new_context()\n\n # Create a new page\n page = await context.new_page()\n\n # Navigate to a URL\n await page.goto(\"https://example.com\")\n\n return \"Page loaded!\"\n```\n\n### Web Scraping Example\n\nHere's a complete example of web scraping with the plugin:\n\n```python\nfrom litestar import get\nfrom playwright.async_api import Browser\n\n@get(\"/scrape\")\nasync def scrape_website(playwright_browser: Browser) -> dict:\n # Create a new context\n context = await playwright_browser.new_context()\n\n try:\n # Create a new page\n page = await context.new_page()\n\n # Navigate to a website\n await page.goto(\"https://example.com\")\n\n # Extract information\n title = await page.title()\n content = await page.content()\n\n return {\n \"title\": title,\n \"content_length\": len(content)\n }\n finally:\n # Always clean up\n await context.close()\n```\n\n### Multiple Playwright Plugins Example\n\nYou can use multiple Playwright plugins in a single application for different use cases:\n\n```python\nfrom litestar import Litestar, get\nfrom playwright.async_api import Browser\nfrom litestar_playwright.config import PlaywrightConfig\nfrom litestar_playwright.plugin import PlaywrightPlugin\n\n# Create different configurations for various browsers\nchrome_config = PlaywrightConfig(\n browser_type=\"chromium\",\n headless=False,\n launch_kwargs={\"args\": [\"--no-sandbox\"]},\n playwright_browser_instance_state_key=\"chrome_browser\",\n)\n\nfirefox_config = PlaywrightConfig(\n browser_type=\"firefox\",\n headless=False,\n playwright_browser_instance_state_key=\"firefox_browser\",\n)\n\n# Route handlers can inject specific browser instances\n@get(\"/chrome-info\")\nasync def chrome_info(chrome_browser: Browser) -> dict:\n return {\"browser\": chrome_browser.browser_type.name}\n\n@get(\"/firefox-info\")\nasync def firefox_info(firefox_browser: Browser) -> dict:\n return {\"browser\": firefox_browser.browser_type.name}\n\n# Use multiple plugins in your app\napp = Litestar(\n plugins=[\n PlaywrightPlugin(config=chrome_config),\n PlaywrightPlugin(config=firefox_config),\n ],\n route_handlers=[chrome_info, firefox_info],\n)\n```\n\nThis approach is useful for:\n\n- **Cross-browser testing**: Test your application across different browsers\n- **Specialized workflows**: Use different browsers for different tasks\n- **CI/CD scenarios**: Run headless browsers for automated testing\n- **Performance testing**: Compare behavior across browser engines\n\n## Support :heart:\n\nIf you have any questions or need help, feel free to open an issue on the [GitHub repository][litestar_playwright].\n\n## Author :person_with_crown:\n\nThis project is maintained by [Hasan Sezer Ta\u015fan][author], It's me :wave:\n\n## Contributing :heart:\n\nAny contributions are welcome! Please follow the [Contributing Guidelines](./CONTRIBUTING.md) to contribute to this project.\n\n## Tasks\n\nClone the repository and cd into the project directory:\n\n```sh\ngit clone https://github.com/hasansezertasan/litestar_playwright\ncd litestar_playwright\n```\n\nThe commands below can also be executed using the [xc task runner](https://xcfile.dev/), which combines the usage instructions with the actual commands. Simply run `xc`, it will pop up an interactive menu with all available tasks.\n\n### `install`\n\nInstall the dependencies:\n\n```sh\nuv sync\nuv run playwright install\n```\n\n### `style`\n\nRun the style checks:\n\n```sh\nuv run --locked tox run -e style\n```\n\n### `ci`\n\nRun the CI pipeline:\n\n```sh\nuv run --locked tox run\n```\n\n### `run-simple`\n\nRun the simple example:\n\n```sh\nuv run python examples/simple.py\n```\n\n### `run-multiple-plugins`\n\nRun the multiple plugins example:\n\n```sh\nuv run python examples/multiple_plugins.py\n```\n\n## License\n\n`litestar-playwright` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n\n## Changelog :memo:\n\nFor a detailed list of changes, please refer to the [CHANGELOG](./CHANGELOG.md).\n\n<!-- Refs -->\n\n[author]: https://github.com/hasansezertasan\n[litestar_playwright]: https://github.com/hasansezertasan/litestar-playwright\n",
"bugtrack_url": null,
"license": null,
"summary": "Playwright integration for Litestar.",
"version": "0.1.0",
"project_urls": {
"changelog": "https://github.com/hasansezertasan/litestar-playwright/blob/main/CHANGELOG.md",
"documentation": "https://github.com/hasansezertasan/litestar-playwright#readme",
"homepage": "https://github.com/hasansezertasan/litestar-playwright",
"issues": "https://github.com/hasansezertasan/litestar-playwright/issues",
"releasenotes": "https://github.com/hasansezertasan/litestar-playwright/releases",
"source": "https://github.com/hasansezertasan/litestar-playwright.git"
},
"split_keywords": [
"automation",
" browser",
" litestar",
" litestar-extension",
" litestar-playwright",
" litestar-plugin",
" playwright",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "16e1511ce73893271243f3766a141012cb2a905f668918224dd77f5761ed038f",
"md5": "a5acf2a1fda12d139135eee1848034f6",
"sha256": "71a6706195d18f71ea7517d6973f5a5a67316f6ff7eec2efb467a5a4a9c478c1"
},
"downloads": -1,
"filename": "litestar_playwright-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a5acf2a1fda12d139135eee1848034f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8180,
"upload_time": "2025-09-06T17:50:44",
"upload_time_iso_8601": "2025-09-06T17:50:44.406959Z",
"url": "https://files.pythonhosted.org/packages/16/e1/511ce73893271243f3766a141012cb2a905f668918224dd77f5761ed038f/litestar_playwright-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d07ba4e8c0121dedc50839d0e1a6d7398114ffa0888e3519e8e1aa8f3d13a1fe",
"md5": "b7047b125149f5d666c1d8fb4797ceab",
"sha256": "a5e2b5a1a40191e079d1a26d1d39031db761fec8ed3c655b22b346d3fa1c4e97"
},
"downloads": -1,
"filename": "litestar_playwright-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b7047b125149f5d666c1d8fb4797ceab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 262096,
"upload_time": "2025-09-06T17:50:45",
"upload_time_iso_8601": "2025-09-06T17:50:45.496288Z",
"url": "https://files.pythonhosted.org/packages/d0/7b/a4e8c0121dedc50839d0e1a6d7398114ffa0888e3519e8e1aa8f3d13a1fe/litestar_playwright-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 17:50:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hasansezertasan",
"github_project": "litestar-playwright",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "litestar-playwright"
}
JSON
