187 lines
6.5 KiB
Markdown
187 lines
6.5 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)
|
|
|
|
---
|
|
|
|
## Setup Instructions
|
|
|
|
Before running the tests, make sure the environment is set up correctly for both the application and the test database.
|
|
|
|
### Application Setup
|
|
|
|
1. **Install Required Dependencies** (Python version 3.9 or higher is recommended):
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
2. **Run the Application**:
|
|
Navigate to the `src` directory and start the application:
|
|
```bash
|
|
cd src
|
|
python main.py
|
|
```
|
|
Alternatively, use Docker:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
Once the server starts, ensure the app is accessible at the base URL defined in `playwright_config.py`. By default, it should be `http://localhost:5002`.
|
|
|
|
### 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.
|
|
|
|
---
|
|
|
|
## 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
|
|
```
|
|
|
|
---
|
|
|
|
## 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. **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.
|
|
|
|
---
|
|
|
|
## Additional Notes
|
|
|
|
- The app server is started with test-specific configurations (`app_server` fixture) that ensure end-to-end isolation.
|
|
- Tests requiring authentication use an admin user defined in the `test_users` fixture:
|
|
- Email: `test.admin@test.com`
|
|
- Password: `TestAdmin123`
|
|
- Ensure no sensitive data or configurations are hardcoded in the test scripts. |