nirtal85 · nirtal85 · Jan 12, 2026 · Jan 12, 2026
diff --git a/README.md b/README.md
@@ -1,20 +1,48 @@
-# 🎭 Playwright Python Example 🎭
+<div align="center">
 
-![twitter](https://img.shields.io/twitter/follow/NirTal2)
-![YouTube Channel](https://img.shields.io/youtube/channel/subscribers/UCQjS-eoKl0a1nuP_dvpLsjQ?label=YouTube%20Channel)
-![dev run](https://github.com/nirtal85/Playwright-Python-Example/actions/workflows/devRun.yml/badge.svg)
-![nightly](https://github.com/nirtal85/Playwright-Python-Example/actions/workflows/nightly.yml/badge.svg)
-[![uv](https://img.shields.iodpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
-[![Ruff](https://img.shields.iodpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+<img height="120" src="https://cdn.simpleicons.org/playwright/2EAD33"/>
+
+# Enterprise-Grade Playwright Python Architecture
+### The Ultimate Boilerplate for Scalable, Robust, and Modern UI Automation
+
+[![Twitter Follow](https://img.shields.io/twitter/follow/NirTal2?style=social)](https://twitter.com/NirTal2)
+[![YouTube](https://img.shields.io/youtube/channel/subscribers/UCQjS-eoKl0a1nuP_dvpLsjQ?style=social)](https://www.youtube.com/channel/UCQjS-eoKl0a1nuP_dvpLsjQ)
+![CI Status](https://github.com/nirtal85/Playwright-Python-Example/actions/workflows/devRun.yml/badge.svg)
+![Nightly Build](https://github.com/nirtal85/Playwright-Python-Example/actions/workflows/nightly.yml/badge.svg)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+[View Live Report](https://nirtal85.github.io/Playwright-Python-Example/) • [Read The Docs](https://www.test-shift.com) • [Report Bug](https://github.com/nirtal85/Playwright-Python-Example/issues)
+
+</div>
+
+---
+
+## 🚀 About The Project
+
+This repository is a **Production-Ready Reference Architecture** for building next-generation test automation using **Playwright** and Python.
+
+It goes beyond basic scripts to demonstrate a fully scalable framework with advanced features like Accessibility Testing (A11y), visual tracing, and cloud integration, tailored for modern DevOps pipelines.
 
 <p align="center">
   <a href="https://automation.co.il/%d7%a7%d7%95%d7%a8%d7%a1-%d7%90%d7%95%d7%98%d7%95%d7%9e%d7%a6%d7%99%d7%94-%d7%a4%d7%99%d7%99%d7%aa%d7%95%d7%9f-python-automation/">
-    <img src="resources/images/automation_college_playwright_course.jpeg" alt="Automation College - Playwright Python Course" />
+    <img src="resources/images/automation_college_playwright_course.jpeg" alt="Automation College - Playwright Python Course" width="600" style="border-radius: 10px;" />
   </a>
 </p>
 
+### ✨ Key Features
+* **Modern Tooling:** Powered by `uv` for blazing fast package management and `Ruff` for linting.
+* **Accessibility First:** Integrated **Axe** scans to ensure your app is accessible to everyone.
+* **Deep Debugging:** Full integration with **Playwright Traces** and Video recording linked directly to Allure Reports.
+* **Cloud Scale:** Native integration with **BrowserStack** for cross-browser testing on real devices.
+* **CI/CD Optimization:** Parallel execution strategies and dynamic version syncing for GitHub Actions.
+
+---
+
 ## 📃 Articles written about this project
 
+This project implements the concepts discussed in the following **TestShift** articles:
+
 * [Test Automation - How To Use Custom User Agent in Selenium Python or Playwright Python to Avoid Security Bots](https://www.test-shift.com/posts/test-automation-how-to-use-custom-user-agent-in-selenium-python-or-playwright-python-to-avoid-security-bots)
 * [Test Automation - How to Use Dynamic Base URLs with Selenium And Playwright Python in GitHub Actions](https://www.test-shift.com/posts/test-automation-how-to-use-dynamic-base-urls-with-selenium-and-playwright-python-in-github-actions)
 * [Test Automation - Maximizing Browser Window With Playwright Python And Pytest](https://www.test-shift.com/posts/test-automation-maximizing-browser-window-with-playwright-python-and-pytest)
@@ -29,136 +57,111 @@
 * [From Open Source to Industry Sponsorship: The TestShift Journey with BrowserStack](https://www.test-shift.com/posts/from-open-source-to-enterprise-sponsorship-the-testshift-journey-with-browserstack)
 * [From Selenium to Playwright: A Data-Driven Look at the Shifting Landscape of Test Automation](https://www.test-shift.com/posts/from-selenium-to-playwright-a-data-driven-look-at-the-shifting-landscape-of-test-automation)
 
+---
+
 ## 🛠️ Tech Stack
 
-| Tool                                                                     | Description                                                                                         |
-|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
-| [allure-pytest](https://pypi.org/project/allure-pytest/)                 | Allure reporting with your Pytest tests for better reporting                                        |
-| [axe-playwright-python](https://pypi.org/project/axe-playwright-python/) | Python library for running accessibility checks with Playwright                                     |
-| [playwright](https://pypi.org/project/playwright/)                       | Python library to automate the Chromium, WebKit, and Firefox browsers through a single API.         |
-| [pytest](https://pypi.org/project/pytest/)                               | Popular testing framework for Python                                                                |
-| [pytest-base-url](https://pypi.org/project/pytest-base-url/)             | Pytest plugin for setting a base URL for your tests                                                 |
-| [pytest-playwright](https://pypi.org/project/pytest-playwright/)         | Pytest plugin for Playwright integration for browser automation testing                             |
-| [pytest-split](https://pypi.org/project/pytest-split/)                   | Pytest plugin which splits the test suite to equally sized sub suites based on test execution time. |
-| [requests](https://pypi.org/project/requests/)                           | Versatile library for making HTTP requests in Python                                                |
+| Tool                                                              | Description & Why We Use It                                      |
+|-------------------------------------------------------------------|------------------------------------------------------------------|
+| [Playwright](https://pypi.org/project/playwright/)                | The modern standard for reliable, flaky-free browser automation. |
+| [Pytest](https://pypi.org/project/pytest/)                        | The most powerful testing framework for Python.                  |
+| [Axe Playwright](https://pypi.org/project/axe-playwright-python/) | For automated accessibility (A11y) compliance testing.           |
+| [Allure](https://pypi.org/project/allure-pytest/)                 | For beautiful, data-rich test reports including Traces & Video.  |
+| [Pytest Split](https://pypi.org/project/pytest-split/)            | To intelligently split test suites for parallel execution.       |
+| [Requests](https://pypi.org/project/requests/)                    | For API interactions and test data setup.                        |
+
+### 🌐 Cloud Testing Provider
 
-## 🌐 Browser Testing
+This project is powered by **[BrowserStack](https://www.browserstack.com)**, enabling high-scale cross-browser and mobile testing on real devices in the cloud.
 
-This project is tested with [BrowserStack](https://www.browserstack.com), enabling cross-browser and mobile testing on real devices in the cloud.
+---
 
-## ⚙️ Setup Instructions
+## ⚙️ Getting Started
 
-### Clone the project
+### 1. Clone
 
 ```bash
 git clone https://github.com/nirtal85/Playwright-Python-Example
 cd playwright-python
 ```
 
-### Create and activate a virtual environment then Install project dependencies
+### 2. Install (The Modern Way)
+
+We use uv for lightning-fast installations.
+
+Windows (PowerShell):
+
 
-#### PowerShell installation in windows:
 ```bash
+python -m pip install uv
 python -m uv venv
 .venv\Scripts\Activate.ps1
-python -m ensurepip --upgrade
-python -m pip install uv
 uv sync --all-extras --dev
+playwright install
 ```
 
-#### For Mac:
+Mac/Linux:
+
 ```bash
 python3 -m pip install uv
 uv venv
 source .venv/bin/activate
 uv sync --all-extras --dev
-```
-
-### Install playwright
-
-```bash
 playwright install
 ```
 
-## 🏃‍♂️ Running Tests
+## 🏃‍♂️ Execution
+
+Run all tests (Chromium by default):
 
 ```bash
 pytest
 ```
 
-When no browser was selected then chrome will be used.
-
-* Run according to tags:
+Run specific suite (Tags):
 
 ```bash
-pytest -m <tag_name>
+pytest -m sanity
 ```
 
-## 📊 Viewing Test Results
-
-### Install Allure Commandline To View Test results
+## 📊 Results, Traces & Debugging
 
-#### For Windows:
+We use Allure for reporting and Playwright Traces for debugging.
 
-Follow the instructions [here](https://scoop.sh/) to install Scoop.<br>
-Run the following command to install Allure using Scoop:
+Viewing Reports Locally
+Windows (via Scoop):
 
 ```bash
 scoop install allure
+allure serve allure-results
 ```
 
-#### For Mac:
+Mac (via Brew):
 
 ```bash
 brew install allure
-```
-
-### View Results Locally:
-
-```bash
 allure serve allure-results
 ```
 
-### View Results Online:
-
-[View allure results via Github pages](https://nirtal85.github.io/Playwright-Python-Example/)
+👉 [See a Live Example of the Report Here](https://nirtal85.github.io/Playwright-Python-Example/)
 
-### View trace results:
+### 🕵️‍♀️ Using the Trace Viewer
 
-1. Navigate to the [Playwright Trace Viewer](https://trace.playwright.dev/)
-2. Locate the trace file stored under the test-results folder. This file is generated after running your tests. Click on the 'Upload' button in the Playwright Trace Viewer and select your trace file.
-3. After uploading, the trace viewer will display a detailed timeline of events that occurred during your test. This includes network requests, JavaScript execution, and browser interactions. You can click on individual events for more details.
+Navigate to the Playwright Trace Viewer.
 
-## ℹ️ View Help And Other CLI Options
+Drag & Drop the trace file (located in test-results/) generated after a failure.
 
-```bash
-pytest --help
-```
-
-### Pre Commit
+Time Travel: Move back and forth in the timeline to see exactly what happened (Network, DOM, Console).
 
-#### Run Pre Commit Checks Automatically
+<div align="center">
 
-```bash
-pre-commit install
-pre-commit install --hook-type commit-msg
-```
+Found this project useful?
+If this architecture helped you solve a problem or save time, consider supporting the work!
 
-#### Bump Pre Commit Hooks Version
+<a href="https://www.buymeacoffee.com/nirtal"> <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="60" alt="Buy Me A Coffee" /> </a>
 
-```bash
-pre-commit autoupdate
-```
-
-#### Run Pre Commit Checks Manually On The Entire Project
-
-```bash
-pre-commit run --all-files
-```
-## ☕ Support
+<br />
 
-If you find this project helpful, you can support my work by buying me a coffee:
+Visit TestShift.com for more Architectural Insights
 
-<p><a href="https://www.buymeacoffee.com/nirtal">
-<img align="left" src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="50" width="210" alt="Buy Me A Coffee" />
-</a></p><br><br>
+</div>