Skip to content

Commit e38457a

Browse files
faruklmu17faruklmu17
committed
made changes
1 parent 0a2f537 commit e38457a

1 file changed

Lines changed: 169 additions & 73 deletions

File tree

‎README.md‎

Lines changed: 169 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,234 @@
11
# Playwright Python Testing Framework
22

3-
A modular, pytest-based Playwright framework for testing React applications (or any web apps) in Python.
4-
This framework includes support for:
3+
A modular, pytest-based **Playwright (Python)** framework for web UI testing.
54

6-
* **Page Object Model** (POM) for clean, maintainable test code
7-
* **Data-driven testing** via JSON fixtures
8-
* **Visual regression** with baseline snapshots and automatic diffs
9-
* **Screenshots & videos** on failures for easier debugging
10-
* **Environment configuration** using `.env` files
11-
* **Authenticated session reuse** using Playwright's `storageState`
12-
* **HTML & JUnit reporting** via `pytest-html` and JUnit XML
13-
* **Optional Allure reporting** for advanced dashboards
14-
* **CLI & CI integration** with GitHub Actions and GitHub Pages
5+
This repo is set up so that a new user can:
6+
1) **Sign up once** on the demo page,
7+
2) Automatically **save credentials to `.env`** and the **session to `auth/storage_state.json`**, and
8+
3) **Reuse the logged-in session** on every test run — no login code inside tests.
159

1610
---
17-
x
18-
## 🚀 Getting Started
1911

20-
Follow these steps to set up and verify that the framework is working correctly on your machine.
12+
## ✅ What’s Included
2113

22-
### ✅ Prerequisites
14+
- **Page Object Model (POM)** for clean, maintainable tests
15+
- **Signup-first flow** that persists credentials + session
16+
- **Global fixtures** via `conftest.py` (one place to manage browser/context/page)
17+
- **Sample tests** to verify setup
18+
- **HTML/JUnit reports** (via `pytest-html`, JUnit XML)
19+
- **CI-friendly** configuration (pytest, reports)
2320

24-
- Python 3.8 or later installed
25-
- Git installed
26-
- Google Chrome or Chromium installed
27-
- Node.js (optional, for Git hooks with Husky)
21+
> Tested against **pytest 8+** and **Playwright 1.45+**.
2822
2923
---
3024

31-
### 🪜 Step-by-Step Setup
32-
33-
#### 1. **Clone the Repository**
34-
This copies the framework into your machine.
25+
## 🧭 First-Time Setup — Step by Step (with explanations)
3526

27+
### 0) Clone the repository
3628
```bash
3729
git clone https://github.com/your-username/playwright_python_framework.git
3830
cd playwright_python_framework
3931
```
32+
**Why?** You need the project files locally.
4033

41-
#### 2. **Create a Virtual Environment**
42-
Keeps your project dependencies isolated from your system Python.
34+
---
4335

36+
### 1) Create & activate a virtual environment
4437
```bash
4538
python -m venv .venv
46-
source .venv/bin/activate # macOS/Linux
47-
# .\.venv\Scripts\activate # Windows
39+
# macOS/Linux:
40+
source .venv/bin/activate
41+
# Windows (PowerShell):
42+
# .venv\Scripts\Activate.ps1
4843
```
44+
**Why?** Keeps your project’s Python packages isolated from system Python.
4945

50-
#### 3. **Install Dependencies**
51-
Installs all required Python libraries and Playwright browsers.
46+
---
5247

48+
### 2) Install Python deps and Playwright browsers
5349
```bash
5450
pip install -r requirements.txt
5551
playwright install
5652
```
53+
**Why?** Installs pytest, Playwright, and helpers. `playwright install` downloads the browser binaries Playwright drives.
5754

58-
#### 4. **Bootstrap Signup**
59-
Before running any tests, you must create a test account.
60-
This script will **sign up on the demo app** and save your credentials into a `.env` file automatically.
55+
---
6156

57+
### 3) Bootstrap the first user (signup → writes `.env` + saves session)
6258
```bash
63-
python scripts/bootstrap_signup.py --name "Test User" --email testuser@example.com --password "MyPass123!"
59+
python scripts/bootstrap_signup.py --name "Jane Doe" --email "jane@example.com" --password "StrongPass123"
6460
```
61+
> macOS tip: If your password contains `!` or `$`, wrap it in **single quotes**: `'StrongPass!23'`.
62+
63+
**What this does:**
64+
- Opens the demo **Sign Up** page: `https://faruk-hasan.com/automation/signup.html`
65+
- Fills **username** (`#username`), **email** (`#email`), **password** (`#password`), **confirm password** (`#confirmPassword`)
66+
- Clicks the **Sign Up** button (role: button, name: “Sign Up”)
67+
- Writes your credentials to **`.env`**:
68+
```env
69+
SIGNUP_NAME=Jane Doe
70+
SIGNUP_EMAIL=jane@example.com
71+
SIGNUP_PASSWORD=StrongPass123
72+
STORAGE_STATE=auth/storage_state.json
73+
```
74+
- Saves the logged-in session to **`auth/storage_state.json`**
75+
76+
**Why?** From now on, tests start **already authenticated**. No login steps inside tests.
77+
78+
---
6579

66-
What happens here:
67-
- Navigates to the signup page.
68-
- Fills in your provided name, email, and password.
69-
- Submits the form.
70-
- Saves your credentials in `.env` so tests can use them.
80+
### 4) Confirm the bootstrap worked
81+
Ensure these now exist:
82+
- `.env` (contains `SIGNUP_NAME`, `SIGNUP_EMAIL`, `SIGNUP_PASSWORD`, `STORAGE_STATE`)
83+
- `auth/storage_state.json` (a non-empty JSON file)
7184

72-
#### 5. **Run the Sample Test**
73-
Run the included test to confirm everything is set up correctly.
85+
**Why?** `conftest.py` uses these to build an authenticated Playwright context automatically.
7486

87+
---
88+
89+
### 5) Run the sample test (quick health check)
7590
```bash
7691
pytest tests/test_sample.py -vv
7792
```
93+
**What this does:** Opens the signup page and asserts the title and required form elements exist.
7894

79-
Expected result:
80-
- Test should **pass** ✅ if the framework is installed and configured properly.
95+
**Success looks like:**
96+
```
97+
collected 1 item
98+
tests/test_sample.py::test_framework_setup PASSED [100%]
99+
```
81100

82-
#### 6. **View Reports**
83-
After running tests, open the HTML report:
101+
---
84102

103+
### 6) Run the full test suite
85104
```bash
86-
open reports/html/report.html # macOS
87-
start reports\html\report.html # Windows
105+
pytest -vv
88106
```
107+
**Why?** Verifies the project runs end-to-end under pytest.
108+
If you kept the bootstrap test, see the next section to run it only on demand.
89109

90110
---
91111

92-
## 🔐 Environment Variables
112+
## 🔁 Running the one-time signup test only when needed (recommended)
93113

94-
The `.env` file is created automatically during signup, but you can also edit it manually.
114+
If you keep `tests/test_signup_and_save_session.py`, mark it and skip by default so signup only runs when you ask for it:
95115

96-
```env
97-
BASE_URL=https://faruk-hasan.com/automation/signup.html
98-
LOGIN_EMAIL=testuser@example.com
99-
LOGIN_PASSWORD=MyPass123!
116+
**`pytest.ini`**
117+
```ini
118+
[pytest]
119+
markers =
120+
sample: quick setup verification test
121+
bootstrap: one-time signup & session save
122+
addopts = -m "not bootstrap"
100123
```
101124

102-
These values are used by tests to log in without signing up each time.
125+
- Daily runs:
126+
```bash
127+
pytest
128+
```
129+
(Bootstrap test is excluded.)
130+
- When you actually need to re-bootstrap:
131+
```bash
132+
pytest -m bootstrap -vv
133+
```
103134

104135
---
105136

106-
## 🧪 Writing Your Own Tests
137+
## 🔒 Headless vs. Headed (seeing the browser)
107138

108-
- Add new tests inside the `tests/` folder.
109-
- Use the `page` fixture provided by Playwright to interact with the browser.
110-
- Example:
139+
The browser mode is controlled in `conftest.py` within the `browser` fixture.
140+
To **watch the browser**, set `headless=False` there:
111141

112142
```python
113-
def test_example(page):
114-
page.goto("https://example.com")
115-
assert page.title() == "Example Domain"
143+
browser = p.chromium.launch(headless=False)
144+
```
145+
146+
---
147+
148+
## 🔐 Rotating credentials / re-signing up
149+
150+
If login fails or the session is stale, quickly create a new user + session:
151+
152+
```bash
153+
python scripts/bootstrap_signup.py --force --random-email --name "New User" --password 'NewStrongPass!23'
154+
```
155+
156+
**What `--force` does:** deletes old `auth/storage_state.json` and overwrites creds in `.env`.
157+
158+
---
159+
160+
## 📊 Test Reports (HTML)
161+
162+
### One-time setup
163+
```bash
164+
pip install pytest-html pytest-metadata
165+
```
166+
167+
### Generate a report (one-off)
168+
```bash
169+
pytest -vv --html=reports/html/report.html --self-contained-html
170+
```
171+
172+
Open the report in your browser:
173+
```bash
174+
open reports/html/report.html # macOS
175+
start reports\html\report.html # Windows
176+
```
177+
178+
### Always generate reports automatically
179+
Add this to your `pytest.ini`:
180+
```ini
181+
[pytest]
182+
addopts = --html=reports/html/report.html --self-contained-html
183+
```
184+
185+
---
186+
187+
## 🧩 Project Structure
188+
189+
```
190+
playwright_python_framework/
191+
├─ auth/
192+
│ └─ storage_state.json
193+
├─ pages/
194+
│ └─ signup_page.py
195+
├─ scripts/
196+
│ └─ bootstrap_signup.py
197+
├─ tests/
198+
│ ├─ test_sample.py
199+
│ └─ test_signup_and_save_session.py
200+
├─ .env.example
201+
├─ conftest.py
202+
├─ pytest.ini
203+
├─ requirements.txt
204+
└─ README.md
116205
```
117206

118207
---
119208

120-
## 🤖 Common Commands
209+
## 🧾 .gitignore
121210

122-
| Action | Command |
123-
|---------------------------|----------------------------------------|
124-
| Run all tests | `pytest` |
125-
| Run one test file | `pytest tests/test_sample.py` |
126-
| Run with detailed output | `pytest -vv` |
127-
| View HTML report | Open `reports/html/report.html` |
211+
```
212+
.env
213+
auth/storage_state.json
214+
.pytest_cache/
215+
__pycache__/
216+
.venv/
217+
reports/
218+
```
128219

129220
---
130221

131-
## 🎉 You’re Ready!
222+
## 🔗 Handy Commands
223+
224+
```bash
225+
pytest tests/test_sample.py -vv
226+
pytest -vv
227+
python scripts/bootstrap_signup.py --name "Jane Doe" --email "jane@example.com" --password "StrongPass123"
228+
python scripts/bootstrap_signup.py --force --random-email --name "New User" --password 'NewStrongPass!23'
229+
pytest -vv --html=reports/html/report.html --self-contained-html
230+
```
132231

133-
Now you can:
134-
- Run tests to validate your setup
135-
- Extend the framework with new pages and tests
136-
- Use `.env` to manage login credentials automatically
232+
---
137233

138-
This project is **beginner-friendly** — just follow the steps above, and you’ll be up and running with a professional-grade Playwright testing framework.
234+
**You’re set!**

0 commit comments

Comments
 (0)