Skip to content

Commit 5762f6b

Browse files
colinmurphycolinmurphy
committed
Updated testing docs. Added script to setup tests locally.
1 parent f324c52 commit 5762f6b

File tree

2 files changed

+315
-28
lines changed

2 files changed

+315
-28
lines changed

‎plugins/hwp-previews/TESTING.md‎

Lines changed: 154 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,26 @@
33
## Table of Contents
44

55
- [Overview](#overview)
6-
- [Directory Structure](#directory-structure)
7-
- [Technologies](#technologies)
6+
- [Directory Structure](#directory-structure)
7+
- [Technologies](#technologies)
88
- [Usage](#usage)
99
- [Running Tests](#running-tests)
1010
- [GitHub Actions](#github-actions)
1111
- [Setup Tests Locally](#setup-tests-locally)
12+
- [Prerequisites](#prerequisites)
13+
- [Docker Setup](#docker-setup)
14+
- [What the Setup Script Does](#what-the-setup-script-does)
15+
- [Running Tests Locally](#running-tests-locally)
16+
- [Troubleshooting](#troubleshooting)
17+
- [Contributing](#contributing)
1218

1319
---
1420

1521
## Overview
1622

17-
HWP Previews comes with automated tests for unit, integration, and acceptance (E2E) scenarios.
23+
HWP Previews comes with automated tests for unit, integration, and acceptance (E2E) scenarios to ensure code quality and functionality.
1824

19-
## Directory Structure
25+
### Directory Structure
2026

2127
A list of related files and directories for testing:
2228

@@ -27,6 +33,7 @@ bin/
2733
├── run-e2e.sh # Run E2E (Playwright) tests
2834
├── run-coverage.sh # Generate coverage reports
2935
└── local/
36+
├── setup-docker-env.sh # Setup Docker environment
3037
├── run-unit-tests.sh # Run unit tests in Docker with Codeception
3138
├── run-e2e-tests.sh # Run e2e tests in Docker with Playwright
3239
├── run-qa.sh # Run php code quality checks with PHPStan, Psalm and PHPCS
@@ -46,28 +53,27 @@ tests/
4653
.env.dist # Example environment variables for testing
4754
codeception.dist.yml # Main Codeception config
4855
```
49-
---
5056

51-
## Technologies
57+
### Technologies
5258

5359
We use the following technologies to run our tests:
5460

55-
- [Codeception](https://codeception.com/)
56-
- [WPBrowser](https://wpbrowser.wptestkit.dev/)
57-
- [WPUnit](https://github.com/lipemat/wp-unit)
58-
- [Docker](https://www.docker.com/)
59-
- [Composer](https://getcomposer.org/)
60-
- [Playwright](https://playwright.dev/)
61-
- [npm](https://www.npmjs.com/)
61+
- [Codeception](https://codeception.com/) - PHP testing framework
62+
- [WPBrowser](https://wpbrowser.wptestkit.dev/) - WordPress-specific testing tools
63+
- [WPUnit](https://github.com/lipemat/wp-unit) - WordPress unit testing
64+
- [Docker](https://www.docker.com/) - Containerized testing environment
65+
- [Composer](https://getcomposer.org/) - PHP dependency management
66+
- [Playwright](https://playwright.dev/) - End-to-end testing framework
67+
- [npm](https://www.npmjs.com/) - JavaScript package manager
6268

6369
---
6470

6571
## Usage
6672

67-
Currently, the plugin has the following suite of tests:
73+
The plugin includes the following test suites:
6874

6975
1. **WP Unit Tests** – Unit and Integration Tests
70-
2. **E2E Tests** – Acceptance tests
76+
2. **E2E Tests** – Acceptance tests using Playwright
7177

7278
### Running Tests
7379

@@ -78,31 +84,151 @@ Currently, the plugin has the following suite of tests:
7884
| `composer run test:e2e` | Run end-to-end (E2E) acceptance tests |
7985
| `composer run test` | Run all available test suites |
8086

87+
### GitHub Actions
88+
89+
Automated testing runs on every pull request via GitHub Actions for a modified plugin:
90+
91+
| Workflow | Description | Status |
92+
|-------------------------|---------------------------------------------|--------|
93+
| **Code Quality** | Runs static analysis and linting checks | [View Workflow](../../actions/workflows/code-quality.yml) |
94+
| **E2E Tests** | Runs Playwright end-to-end acceptance tests | [View Workflow](../../actions/workflows/e2e.yml) |
95+
| **Codeception (WPUnit)** | Runs unit and integration tests | [View Workflow](../../actions/workflows/codeception.yml) |
96+
97+
98+
>[!IMPORTANT]
99+
> Test coverage for WP Unit Tests is **95%**. Any new code will require tests to be added in order to pass CI checks. This is set in [text](codeception.dist.yml) in the parameter `min_coverage`.
100+
81101
---
82102

83-
## GitHub Actions
103+
## Setup Tests Locally
104+
105+
### Prerequisites
106+
107+
- Docker and Docker Compose installed and running
108+
- Composer installed
109+
- Node.js and npm installed (for E2E tests)
110+
- Terminal/command line access
111+
112+
### Docker Setup
113+
114+
>[!NOTE]
115+
> You need Docker running locally before setting up tests. Alternatively, you can copy `.env.dist` to `.env` and update the database details to point to your local database. However, this will make database changes, so we recommend using the Docker setup instead.
84116
85-
We have a few checks which run for a new PR being merged to main
117+
To set up your local Docker environment, run:
86118

87-
| Workflow | Description | Link |
88-
|-------------------------|---------------------------------------------|----------------------------------------------------------------------|
89-
| Code Quality | Runs static analysis and linting checks | [View Workflow](../../actions/workflows/code-quality.yml) |
90-
| E2E Tests | Runs Playwright end-to-end acceptance tests | [View Workflow](../../actions/workflows/e2e.yml) |
91-
| Codeception (WPUnit) | Runs unit and integration tests | [View Workflow](../../actions/workflows/codeception.yml) |
119+
```shell
120+
sh bin/local/setup-docker-env.sh
121+
```
122+
123+
This script will automatically handle the complete Docker environment setup process.
124+
125+
### What the Setup Script Does
126+
127+
The setup script performs the following operations:
128+
129+
#### 1. Environment Verification
130+
- ✅ Checks that Docker is running
131+
- ✅ Verifies required files exist
132+
133+
#### 2. Configuration Setup
134+
- 📁 Copies `bin/local/.env.local` to `.env`
135+
- Uses local development configuration (different from `.env.dist`)
136+
- Sets appropriate database credentials and WordPress settings
92137

138+
#### 3. Docker Container Management
139+
- 🐳 Runs `composer run docker:build`
140+
- Executes `sh bin/build-docker.sh` to create the Docker container
141+
- Builds WordPress environment with PHP 8.2
142+
- 🚀 Runs `docker compose up -d` to start the container in detached mode
143+
- Creates container named `hwp-previews-wordpress-1`
144+
- Sets up WordPress with test database
93145

94-
> **INFO:**
95-
> All tests are automatically run on every pull request via GitHub Actions. You can review test results and logs directly in the "Checks" tab of your PR on GitHub.
146+
#### 4. Code Coverage Setup
147+
- 🔧 Installs and configures PCOV extension (preferred for performance)
148+
- 🔄 Falls back to XDebug if PCOV installation fails
149+
- ⚙️ Configures coverage settings automatically
150+
- 🔄 Restarts container to ensure extensions are loaded
96151

97-
> **IMPORTANT:**
98-
> Test coverage for WP Unit Tests is 95%. Any new code will require tests to be added in order to pass.
152+
#### 5. WordPress Installation
153+
- 📝 Installs WordPress if not already present
154+
- 🔌 Activates the plugin automatically
155+
- ✅ Verifies the installation is working correctly
156+
157+
### Running Tests Locally
158+
159+
Once setup is complete, you can run tests using Composer:
160+
161+
```shell
162+
# Run unit tests with coverage
163+
composer run test:unit:coverage
164+
165+
# Run all tests
166+
composer run test
167+
168+
# Run E2E tests
169+
composer run test:e2e
170+
```
171+
172+
For a full list of available test commands, see the [Usage](#usage) section above.
99173

100174
---
101175

102-
## Setup Tests Locally
176+
## Troubleshooting
177+
178+
### Container Issues
179+
180+
```shell
181+
# Check container status
182+
docker ps | grep hwp-previews
183+
184+
# Restart containers if needed
185+
docker compose restart
186+
187+
# View container logs
188+
docker compose logs hwp-previews-wordpress-1
189+
```
190+
191+
### Permission Issues
192+
193+
```shell
194+
# Fix test output permissions
195+
docker exec hwp-previews-wordpress-1 chmod 777 -R tests/_output
196+
```
103197

104-
@TODO
198+
### Coverage Driver Issues
105199

200+
```shell
201+
# Check which coverage driver is available
202+
docker exec hwp-previews-wordpress-1 php -m | grep -E "(pcov|xdebug)"
203+
204+
# Re-run setup if coverage isn't working
205+
sh bin/local/setup-docker-env.sh
206+
```
207+
208+
### WordPress Database Issues
209+
210+
```shell
211+
# Reinstall WordPress
212+
docker exec hwp-previews-wordpress-1 wp core install \
213+
--url=http://localhost \
214+
--title="Test Site" \
215+
--admin_user=admin \
216+
--admin_password=admin \
217+
[email protected] \
218+
--allow-root
219+
```
220+
221+
### Clean Up Environment
222+
223+
```shell
224+
# Stop containers
225+
docker compose down
226+
227+
# Remove containers and volumes (complete cleanup)
228+
docker compose down -v
229+
```
230+
231+
---
106232

107233
## Contributing
108234

0 commit comments

Comments
 (0)