Skip to content

Commit 5eae7c5

Browse files
TerrorSquadTerrorSquad
committed
test: enhance integration testing process with a new Python script
1 parent 9c15ec4 commit 5eae7c5

File tree

6 files changed

+1291
-408
lines changed

6 files changed

+1291
-408
lines changed

‎booster/integrate_booster.sh‎

Lines changed: 47 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ BOOSTER_REPO_URL="https://github.com/TerrorSquad/php-blueprint.git"
77
BOOSTER_TARGET_DIR="php-booster"
88
BOOSTER_INTERNAL_PATH="${BOOSTER_TARGET_DIR}/booster"
99

10+
# --- Local Development Mode ---
11+
# Set BOOSTER_LOCAL_DEV=1 to use local booster directory instead of cloning from GitHub
12+
# Set BOOSTER_LOCAL_PATH to specify the local booster directory path (default: ../booster)
13+
BOOSTER_LOCAL_DEV="${BOOSTER_LOCAL_DEV:-0}"
14+
BOOSTER_LOCAL_PATH="${BOOSTER_LOCAL_PATH:-../booster}"
15+
1016
# --- ANSI color codes ---
1117
GREEN='\033[0;32m'
1218
RED='\033[0;31m'
@@ -79,22 +85,43 @@ function is_ddev_project() {
7985
# --- Core Logic Functions ---
8086

8187
function download_php_booster() {
82-
log "Cloning php-booster from $BOOSTER_REPO_URL..."
83-
# Clean up previous attempts first
84-
rm -rf "$BOOSTER_TARGET_DIR" # Remove target dir if it exists
85-
86-
# Clone only the main branch and only the latest commit for speed
87-
git clone --depth 1 --branch main "$BOOSTER_REPO_URL" "$BOOSTER_TARGET_DIR" || error "Failed to clone booster repository."
88+
if [ "$BOOSTER_LOCAL_DEV" = "1" ]; then
89+
log "Using local php-booster for development..."
90+
# Clean up previous attempts first
91+
rm -rf "$BOOSTER_TARGET_DIR" # Remove target dir if it exists
92+
93+
# Check if local booster path exists
94+
if [ ! -d "$BOOSTER_LOCAL_PATH" ]; then
95+
error "Local booster directory not found at '$BOOSTER_LOCAL_PATH'. Set BOOSTER_LOCAL_PATH or ensure the directory exists."
96+
fi
97+
98+
# Copy the local booster instead of cloning
99+
mkdir -p "$BOOSTER_TARGET_DIR"
100+
cp -R "$BOOSTER_LOCAL_PATH" "$BOOSTER_INTERNAL_PATH" || error "Failed to copy local booster directory."
88101

89-
if [ ! -d "$BOOSTER_TARGET_DIR" ]; then
90-
error "Target directory '$BOOSTER_TARGET_DIR' not found after clone."
91-
fi
102+
if [ ! -d "$BOOSTER_INTERNAL_PATH" ]; then
103+
error "Target directory '$BOOSTER_INTERNAL_PATH' not found after copy."
104+
fi
105+
106+
success "Local php-booster copied successfully from '$BOOSTER_LOCAL_PATH'."
107+
else
108+
log "Cloning php-booster from $BOOSTER_REPO_URL..."
109+
# Clean up previous attempts first
110+
rm -rf "$BOOSTER_TARGET_DIR" # Remove target dir if it exists
111+
112+
# Clone only the main branch and only the latest commit for speed
113+
git clone --depth 1 --branch main "$BOOSTER_REPO_URL" "$BOOSTER_TARGET_DIR" || error "Failed to clone booster repository."
114+
115+
if [ ! -d "$BOOSTER_TARGET_DIR" ]; then
116+
error "Target directory '$BOOSTER_TARGET_DIR' not found after clone."
117+
fi
92118

93-
if [ ! -d "$BOOSTER_INTERNAL_PATH" ]; then
94-
warn "The expected internal structure '$BOOSTER_INTERNAL_PATH' was not found within the cloned repository."
95-
error "Blueprint content directory '$BOOSTER_INTERNAL_PATH' not found."
119+
if [ ! -d "$BOOSTER_INTERNAL_PATH" ]; then
120+
warn "The expected internal structure '$BOOSTER_INTERNAL_PATH' was not found within the cloned repository."
121+
error "Blueprint content directory '$BOOSTER_INTERNAL_PATH' not found."
122+
fi
123+
success "php-booster cloned successfully into '$BOOSTER_TARGET_DIR'."
96124
fi
97-
success "php-booster cloned successfully into '$BOOSTER_TARGET_DIR'."
98125
}
99126

100127
function update_ddev_files() {
@@ -212,9 +239,16 @@ function copy_files() {
212239
if [ -f "$tools_src/$f" ]; then
213240
log " Copying tool '$f'"
214241
cp "$tools_src/$f" tools/
242+
# Set execute permissions for shell scripts
243+
if [[ "$f" == *.sh ]]; then
244+
chmod +x "tools/$f"
245+
fi
215246
elif [ -d "$tools_src/$f" ]; then
216247
log " Copying tool directory '$f'"
217248
cp -R "$tools_src/$f" tools/
249+
# Set execute permissions for shell scripts in the directory
250+
find "tools/$f" -name "*.sh" -exec chmod +x {} \;
251+
find "tools/$f" -name "*.bash" -exec chmod +x {} \;
218252
else
219253
warn " Expected tool file missing: $f"
220254
fi

‎docs/content/4.troubleshooting/1.troubleshooting.md‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
# Troubleshooting
2+
3+
This section covers common issues you might encounter when using the PHP Booster and how to resolve them.
4+
5+
## Integration Issues
6+
7+
### Integration Script Fails
8+
9+
**Problem**: The integration script fails with errors about missing dependencies.
10+
11+
**Solution**:
12+
1. Ensure you have all required tools installed:
13+
```bash
14+
# Check if curl is available
15+
which curl
16+
17+
# For DDEV projects, ensure DDEV is running
18+
ddev status
19+
```
20+
21+
2. Run the integration script in verbose mode to see detailed error messages.
22+
23+
### Files Not Created
24+
25+
**Problem**: Expected booster files are not created in your project.
26+
27+
**Solution**:
28+
1. Check that you ran the integration script from your project root
29+
2. Verify you have write permissions in the project directory
30+
3. Check if your project has any conflicting files that might prevent creation
31+
32+
### Permission Errors
33+
34+
**Problem**: Permission denied errors when running integration.
35+
36+
**Solution**:
37+
```bash
38+
# Ensure execute permissions on scripts
39+
chmod +x tools/runner.sh
40+
chmod +x tools/git-hooks/setup.sh
41+
42+
# For DDEV projects
43+
ddev restart
44+
```
45+
46+
## Git Hooks Issues
47+
48+
### Pre-commit Hook Fails
49+
50+
**Problem**: Pre-commit hook fails with "Could not open input file" errors.
51+
52+
**Solution**: This is usually a path resolution issue in DDEV containers.
53+
54+
1. Check that the hook script has correct file paths:
55+
```bash
56+
# Check pre-commit hook
57+
cat .husky/pre-commit.bash
58+
59+
# Ensure runner script exists
60+
ls -la tools/runner.sh
61+
```
62+
63+
2. For DDEV, restart the container:
64+
```bash
65+
ddev restart
66+
```
67+
68+
### Branch Name Validation Fails
69+
70+
**Problem**: Valid branch names are rejected or invalid ones are accepted.
71+
72+
**Solution**: Check your branch naming configuration:
73+
74+
1. Review the validation config:
75+
```bash
76+
cat validate-branch-name.config.cjs
77+
```
78+
79+
2. Test branch validation manually:
80+
```bash
81+
# Test current branch
82+
node_modules/.bin/validate-branch-name
83+
84+
# Test specific branch name
85+
node_modules/.bin/validate-branch-name -t "feature/PRJ-123-my-feature"
86+
```
87+
88+
3. Common valid patterns:
89+
- `feature/PRJ-123-my-feature`
90+
- `fix/ERM-456-bug-fix`
91+
- `chore/update-docs`
92+
93+
### Commit Message Validation Issues
94+
95+
**Problem**: Commit messages are rejected even when they seem correct.
96+
97+
**Solution**:
98+
1. Ensure you're following Conventional Commits format:
99+
```
100+
type(scope): description
101+
102+
Examples:
103+
feat: add user authentication
104+
fix(auth): correct password validation
105+
chore: update dependencies
106+
```
107+
108+
2. Check commitlint configuration:
109+
```bash
110+
cat commitlint.config.ts
111+
```
112+
113+
## Tool Integration Issues
114+
115+
### Composer Scripts Not Working
116+
117+
**Problem**: `composer ecs`, `composer phpstan`, etc. commands fail.
118+
119+
**Solution**:
120+
1. Verify tools are installed:
121+
```bash
122+
composer show | grep -E "(phpstan|rector|symplify|psalm)"
123+
```
124+
125+
2. For DDEV projects, use DDEV commands:
126+
```bash
127+
ddev composer ecs
128+
ddev composer phpstan
129+
```
130+
131+
3. Check if composer scripts exist:
132+
```bash
133+
cat composer.json | jq '.scripts'
134+
```
135+
136+
### ECS/PHPStan Path Issues
137+
138+
**Problem**: Code quality tools can't find files or have path resolution errors.
139+
140+
**Solution**: This often happens with DDEV containerization.
141+
142+
1. Use the runner script:
143+
```bash
144+
# Instead of direct tool calls
145+
bash tools/runner.sh vendor/bin/ecs check src/
146+
147+
# Use composer scripts (recommended)
148+
ddev composer ecs
149+
```
150+
151+
2. Check tool configurations have correct paths:
152+
```bash
153+
# Check ECS config
154+
cat ecs.php
155+
156+
# Check PHPStan config
157+
cat phpstan.neon.dist
158+
```
159+
160+
## DDEV Issues
161+
162+
### Container Not Starting
163+
164+
**Problem**: DDEV containers fail to start or show errors.
165+
166+
**Solution**:
167+
1. Check DDEV status and logs:
168+
```bash
169+
ddev status
170+
ddev logs
171+
```
172+
173+
2. Restart DDEV:
174+
```bash
175+
ddev restart
176+
```
177+
178+
3. If containers are corrupted, recreate:
179+
```bash
180+
ddev delete -y
181+
ddev start
182+
```
183+
184+
### Performance Issues
185+
186+
**Problem**: DDEV is slow or unresponsive.
187+
188+
**Solution**:
189+
1. Configure Mutagen for better file sync performance (especially on macOS):
190+
```bash
191+
ddev config --mutagen-enabled
192+
ddev restart
193+
```
194+
195+
2. Exclude unnecessary directories from sync:
196+
```yaml
197+
# In .ddev/config.yaml
198+
upload_dirs:
199+
- storage/app/uploads
200+
```
201+
202+
## Testing Issues
203+
204+
### Integration Tests Failing
205+
206+
**Problem**: The test script fails when running integration tests.
207+
208+
**Solution**:
209+
1. Check requirements:
210+
```bash
211+
./tools/internal-test/test-integration.py env-check
212+
```
213+
214+
2. Clean test environment:
215+
```bash
216+
./tools/internal-test/test-integration.py clean
217+
```
218+
219+
3. Run individual test steps to isolate issues:
220+
```bash
221+
# Test setup only
222+
./tools/internal-test/test-integration.py setup
223+
224+
# Test integration only
225+
./tools/internal-test/test-integration.py integrate
226+
227+
# Check status
228+
./tools/internal-test/test-integration.py status
229+
```
230+
231+
### Test Environment Cleanup
232+
233+
**Problem**: Test environments are not cleaned up properly.
234+
235+
**Solution**:
236+
```bash
237+
# Automatic cleanup
238+
./tools/internal-test/test-integration.py clean
239+
240+
# Manual cleanup if script fails
241+
cd tests/laravel/test-project && ddev delete -y
242+
rm -rf tests/laravel/test-project
243+
rm -rf tests/symfony/test-project
244+
245+
# Clean Docker resources if needed
246+
docker system prune -f
247+
```
248+
249+
## IDE Configuration Issues
250+
251+
### VSCode Extensions Not Working
252+
253+
**Problem**: Recommended VSCode extensions don't provide expected functionality.
254+
255+
**Solution**:
256+
1. Check extensions are installed:
257+
```bash
258+
code --list-extensions
259+
```
260+
261+
2. Install missing extensions:
262+
```bash
263+
# Install from workspace recommendations
264+
code --install-extension ms-vscode-remote.remote-containers
265+
code --install-extension DEVSENSE.phptools-vscode
266+
```
267+
268+
3. Check extension settings in `.vscode/settings.json`
269+
270+
### PHPStorm Integration Issues
271+
272+
**Problem**: PHPStorm doesn't recognize the project structure or DDEV.
273+
274+
**Solution**:
275+
1. Install and configure DDEV Integration plugin
276+
2. Set up PHP interpreter to use DDEV:
277+
- Go to Settings → PHP → Servers
278+
- Add new server with DDEV configuration
279+
3. Check `.phpstorm` directory configuration files
280+
281+
## Getting Help
282+
283+
If you're still experiencing issues:
284+
285+
1. Check the [GitHub Issues](https://github.com/TerrorSquad/php-blueprint/issues) for similar problems
286+
2. Run the test script to validate your setup:
287+
```bash
288+
./tools/internal-test/test-integration.py full
289+
```
290+
3. Create a new issue with:
291+
- Your operating system and PHP version
292+
- DDEV version (if applicable)
293+
- Full error output
294+
- Steps to reproduce the issue

0 commit comments

Comments
 (0)