cartflows / docs / wiki / Testing-Guide.md

Testing-Guide.md in CartFlows – Funnel Builder & Checkout Plugin for WooCommerce 3.0.1, at docs/wiki/Testing-Guide.md

228 lines 5.0 KB

Raw Download Zip

1	# Testing Guide
2
3	CartFlows uses two testing frameworks: PHPUnit for PHP unit/integration tests and Playwright for E2E browser tests, with a wp-env Docker environment for local test WordPress instances.
4
5	## PHP Unit Tests
6
7	### Stack
8
9	\| Tool \| Version \| Purpose \|
10	\|------\|---------\|---------\|
11	\| PHPUnit \| ^8 \| Test runner \|
12	\| Yoast PHPUnit Polyfills \| Latest \| PHPUnit 8–10 compatibility shims \|
13	\| PHPStan \| ^1.9 \| Static analysis \|
14	\| szepeviktor/phpstan-wordpress \| ^1.1 \| WordPress-specific PHPStan stubs \|
15
16	### Running Tests
17
18	```bash
19	# Run all PHP unit tests
20	composer test
21
22	# Run directly with PHPUnit
23	vendor/bin/phpunit
24
25	# Run a specific test class
26	vendor/bin/phpunit --filter TestClassName
27
28	# Run a specific test method
29	vendor/bin/phpunit --filter TestClassName::test_method_name
30
31	# Run tests in a specific group
32	vendor/bin/phpunit --group group-name
33	```
34
35	### Test Location
36
37	```
38	tests/php/
39	├── stubs/
40	│ └── cf-stubs.php ← PHPStan stubs for CartFlows classes
41	└── *.php ← PHPUnit test cases
42	```
43
44	### PHPStan Stubs
45
46	PHPStan stubs live at `tests/php/stubs/cf-stubs.php`. These provide type information for CartFlows classes that PHPStan cannot infer.
47
48	Regenerate stubs when plugin classes change significantly:
49
50	```bash
51	composer update-stubs
52	```
53
54	### Static Analysis
55
56	```bash
57	# Run PHPStan static analysis
58	composer phpstan
59	```
60
61	PHPStan configuration is in `phpstan.neon` at the project root. The level and custom rules are defined there.
62
63	### PHPCS Linting
64
65	```bash
66	# Check WordPress coding standards
67	composer lint
68
69	# Auto-fix PHPCS violations
70	composer format
71	```
72
73	---
74
75	## E2E Tests (Playwright)
76
77	### Stack
78
79	\| Tool \| Version \| Purpose \|
80	\|------\|---------\|---------\|
81	\| Playwright \| Latest \| Browser automation + assertions \|
82	\| wp-env \| ^4.2.0 \| Docker-based WordPress environment \|
83	\| `@wordpress/env` \| ^4.2.0 \| wp-env npm package \|
84
85	### Running E2E Tests
86
87	```bash
88	# Headless (CI) mode
89	npm run test:e2e
90
91	# Interactive / headed mode (watch browser)
92	npm run test:e2e:interactive
93
94	# Playwright test runner
95	npm run play:run
96
97	# Playwright interactive mode
98	npm run play:run:interactive
99	```
100
101	### Test Location
102
103	```
104	tests/e2e/
105	└── *.spec.js ← Playwright test files
106	```
107
108	### Writing E2E Tests
109
110	E2E tests follow Playwright's page object model. Tests interact with the CartFlows admin UI and frontend checkout flows through a real (Docker) WordPress environment.
111
112	Example structure:
113
114	```js
115	import { test, expect } from '@playwright/test';
116
117	test( 'user can create a flow', async ( { page } ) => {
118	await page.goto( '/wp-admin/admin.php?page=cartflows' );
119	await page.click( '[data-testid="create-flow"]' );
120	await expect( page.locator( '.wcf-flow-title' ) ).toBeVisible();
121	} );
122	```
123
124	---
125
126	## wp-env (Local Docker Environment)
127
128	`wp-env` provides an isolated WordPress environment for both running E2E tests and local development.
129
130	### Commands
131
132	```bash
133	# Start WordPress Docker environment
134	npm run env:start
135
136	# Stop environment
137	npm run env:stop
138
139	# Clean environment (reset database, keep images)
140	npm run env:clean
141
142	# Destroy environment completely (remove containers + volumes)
143	npm run env:destroy
144	```
145
146	### Configuration
147
148	wp-env is configured in `.wp-env.json` at the project root (or parent directory). Typical configuration includes:
149
150	```json
151	{
152	"core": "WordPress/WordPress#trunk",
153	"plugins": [ "." ],
154	"themes": [],
155	"port": 8888,
156	"testsPort": 8889
157	}
158	```
159
160	The test environment runs on a separate port (8889) from the development environment (8888).
161
162	---
163
164	## Playwright Configuration
165
166	Playwright configuration is typically in `playwright.config.js` at the project root. It specifies:
167	- Base URL pointing to the wp-env test instance
168	- Browser targets (Chromium, Firefox, WebKit)
169	- Screenshot and video settings on failure
170
171	---
172
173	## CI / Automated Testing
174
175	Tests are run in CI against the same wp-env Docker setup. Ensure the environment is running before executing E2E tests.
176
177	### Recommended Test Order
178
179	1. Start wp-env: `npm run env:start`
180	2. Run PHP unit tests: `composer test`
181	3. Run PHP static analysis: `composer phpstan`
182	4. Run E2E tests: `npm run test:e2e`
183	5. Stop wp-env: `npm run env:stop`
184
185	---
186
187	## Code Quality Tools
188
189	### JavaScript
190
191	```bash
192	npm run lint-js # ESLint
193	npm run lint-js:fix # ESLint + auto-fix
194	npm run lint-css # Stylelint
195	npm run lint-css:fix # Stylelint + auto-fix
196	npm run pretty # Prettier check
197	npm run pretty:fix # Prettier auto-fix
198	```
199
200	### PHP
201
202	```bash
203	composer lint # PHPCS
204	composer format # phpcbf auto-fix
205	composer phpstan # PHPStan
206	```
207
208	---
209
210	## Test Exclusions
211
212	PHPCS is configured to exclude these directories from scanning:
213
214	- `admin-core/assets/` (compiled JS/CSS)
215	- `vendor/` (Composer dependencies)
216	- `node_modules/` (npm packages)
217	- `libraries/` (vendored BSF packages)
218	- `tests/php/` (test files — different standards apply)
219
220	---
221
222	## Related Pages
223
224	- [](Contributing-GuideContributing-Guide](Contributing-Guide](Contributing-Guide)
225	- [](Environment-ConfigurationEnvironment-Configuration](Environment-Configuration](Environment-Configuration)
226	- [](WordPress-Coding-StandardsWordPress-Coding-Standards](WordPress-Coding-Standards](WordPress-Coding-Standards)
227	- [](Deployment-GuideDeployment-Guide](Deployment-Guide](Deployment-Guide)
228