177 lines
5.7 KiB
Markdown
177 lines
5.7 KiB
Markdown
# README - End-to-End Authentication Testing Guide
|
|
|
|
This README provides details on how to set up, configure, and run the end-to-end (e2e) authentication tests for the **My
|
|
Managing Tools** application. The tests are implemented using `pytest` with `playwright` for browser automation.
|
|
|
|
## Purpose
|
|
|
|
The e2e tests verify that the authentication system works as expected, including login functionality, session
|
|
validation, and database isolation for testing purposes. These tests ensure the login page behaves properly under
|
|
different scenarios such as unauthenticated access, form validation, and successful user login.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Setup Instructions](#setup-instructions)
|
|
- [Application Setup](#application-setup)
|
|
- [Database Setup](#database-setup)
|
|
2. [Installing Dependencies](#installing-dependencies)
|
|
3. [Running Tests](#running-tests)
|
|
4. [Debugging and Logs](#debugging-and-logs)
|
|
5. [Test Scenarios](#test-scenarios)
|
|
6. [Troubleshooting](#troubleshooting)
|
|
|
|
---
|
|
|
|
## Installing Dependencies
|
|
|
|
Install the required packages for the tests:
|
|
|
|
1. **Playwright and Pytest**:
|
|
Install `pytest-playwright` and playwright dependencies:
|
|
```bash
|
|
pip install pytest-playwright
|
|
playwright install
|
|
playwright install-deps # For Linux systems
|
|
```
|
|
|
|
2. **Project Dependencies**:
|
|
Use the provided `requirements.txt` to install other necessary packages:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Verify Installation**:
|
|
Confirm Playwright is installed and functional:
|
|
```bash
|
|
playwright --version
|
|
```
|
|
|
|
---
|
|
|
|
|
|
### Database Setup
|
|
|
|
The e2e tests are designed to interact with an **isolated test database**. During setup, a temporary SQLite database will be created for each test session.
|
|
|
|
1. **Test Database Initialization**:
|
|
The database is initialized dynamically during the test execution using a custom temporary path. The `test_database` fixture creates a database with the following characteristics:
|
|
- **Temporary Directory**: Ensures no conflicts with the production database.
|
|
- **Admin User Auto-Creation**: Adds an admin account if the environment variables `ADMIN_EMAIL` and `ADMIN_PASSWORD` are set.
|
|
|
|
2. **Environment Variables**:
|
|
Ensure the following environment variables are defined for the test database:
|
|
```env
|
|
DB_PATH="test_mmt_tools.db"
|
|
ADMIN_EMAIL="test.admin@test.com"
|
|
ADMIN_PASSWORD="TestAdmin123"
|
|
```
|
|
|
|
3. **Configuration**:
|
|
The `test_database.py` script handles the database isolation and cleanup after each test session. It ensures that no state is leaked between tests.
|
|
|
|
---
|
|
|
|
## Running Tests
|
|
|
|
To execute the end-to-end authentication tests, run the following commands from the project root.
|
|
|
|
1. **Run All Tests**:
|
|
Execute all e2e tests:
|
|
```bash
|
|
pytest -m "e2e"
|
|
```
|
|
|
|
2. **Run Specific Test**:
|
|
Use the test path and `-k` argument to target specific tests:
|
|
```bash
|
|
pytest tests/test_e2e_authentication.py -k "test_unauthenticated_user_redirected_to_login"
|
|
```
|
|
|
|
3. **Record Test Results**:
|
|
Save test results (HTML report):
|
|
```bash
|
|
pytest --html=test-results/report.html --self-contained-html
|
|
```
|
|
|
|
4. **Parallel Execution**:
|
|
If desired, run tests in parallel:
|
|
```bash
|
|
pytest -n auto
|
|
```
|
|
|
|
---
|
|
|
|
## Debugging and Logs
|
|
|
|
1. **Console Logs**:
|
|
Console errors during page navigation are captured using the `test_page_loads_without_errors` test. Check the pytest
|
|
output for details.
|
|
|
|
2. **Debugging Tools**:
|
|
- Videos and HAR traces are recorded in the `test-results` directory.
|
|
- Use the `page.pause()` method inside a test for interactive debugging with Playwright Inspector.
|
|
|
|
3. **Screenshots and Debug HTML**:
|
|
If a test fails, screenshots and full HTML are saved for post-mortem debugging:
|
|
- `debug_after_login.png`: Screenshot post-login.
|
|
- `debug_page.html`: Captured HTML structure of the page.
|
|
|
|
4. **Manual Debugging**:
|
|
```python
|
|
# Screenshot
|
|
page.screenshot(path="debug_after_login.png")
|
|
|
|
# HTML content
|
|
with open("debug_page.html", "w", encoding="utf-8") as f:
|
|
f.write(page.content())
|
|
```
|
|
|
|
5. **Server Logs**:
|
|
When using the `app_server` fixture, server `stdout` and `stderr` are recorded during the test execution.
|
|
|
|
---
|
|
|
|
|
|
|
|
## Test Scenarios
|
|
|
|
The main authentication tests cover the following scenarios:
|
|
|
|
1. **Unauthenticated User Redirect**:
|
|
Verify that unauthenticated users accessing protected resources are redirected to the login page.
|
|
|
|
2. **Login Page Elements**:
|
|
Validate that key login page elements are visible, such as email/password fields and the submit button.
|
|
|
|
3. **Successful Login**:
|
|
Ensure users can log in successfully with valid credentials and are redirected to the home page.
|
|
|
|
4. **Test Database Isolation**:
|
|
Confirm that the test environment uses an isolated temporary database and does not affect production data.
|
|
|
|
5. **Page Load Without Errors**:
|
|
Ensure that the login page loads without console or HTTP errors.
|
|
|
|
For a full list of test cases, see `tests/test_e2e_authentication.py`.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
- **Server Not Starting**:
|
|
If the server fails to start during testing, confirm the `DB_PATH`, `BASE_URL`, and all dependencies are correctly
|
|
configured in the `.env` file.
|
|
|
|
- **Playwright Issues**:
|
|
Ensure Playwright dependencies (`playwright install`) are installed and functional. Missing browsers or outdated
|
|
Playwright versions can cause tests to fail.
|
|
|
|
- **Database Error**:
|
|
Check that the `tools.db` file or the temporary test database exists and is accessible. Ensure the test database
|
|
environment variables are set correctly during tests.
|
|
|
|
---
|
|
|
|
igurations are hardcoded in the test scripts. |