Enhance development and production scripts in package.json and update README for CSP testing

- Added new npm scripts for production testing with Content Security Policy: `dev:prod` and `preview:prod`.
- Updated README.md to include detailed instructions for development, production testing, and a pre-deployment checklist to ensure security settings are verified before deployment.
This commit is contained in:
2025-11-06 12:54:47 +01:00
parent 993d16d920
commit db6270438f
5 changed files with 449 additions and 2 deletions

132
TESTING.md Normal file
View File

@@ -0,0 +1,132 @@
# Testing & Pre-Deployment Checklist
This document outlines how to test your changes before deploying to production.
## Development Workflow
### 1. **Regular Development** (Fast, no CSP)
```bash
npm run dev
```
- Uses Astro dev server
- Hot reload enabled
- No CSP enforcement
- Best for rapid development
### 2. **Production-like Testing** (Before Deployment)
```bash
npm run dev:prod
```
- Builds the production bundle
- Runs with `server.js` (same as production)
- **Enables CSP** (`ENABLE_SSR_CSP=1`)
- Tests all security headers
- **Use this to catch production issues early!**
### 3. **Quick Production Test** (After Build)
If you've already built:
```bash
npm run preview:prod
```
- Skips rebuild
- Runs existing build with CSP enabled
- Faster than `dev:prod`
## Pre-Deployment Checklist
Before pushing to production, **always test with CSP enabled**:
- [ ] Run `npm run dev:prod` locally
- [ ] Test all interactive features:
- [ ] Mobile menu toggle
- [ ] Language selector
- [ ] Theme switcher (dark/light mode)
- [ ] Contact form
- [ ] Smooth scrolling
- [ ] Latest commits widget (if applicable)
- [ ] RocketChat widget
- [ ] Check browser console for CSP violations
- [ ] Test on multiple browsers (Chrome, Firefox, Safari)
- [ ] Test on mobile devices
- [ ] Run `npm run check` (linting & type checking)
## Common CSP Issues
### Symptom: JavaScript not working in production
**Error in console:** "Refused to execute inline script because it violates CSP directive..."
**Solution:** Check that `'unsafe-inline'` is in the `script-src` directive in `server.js`
### Symptom: External resources blocked
**Error in console:** "Refused to load... because it violates CSP directive..."
**Solution:** Add the domain to the appropriate CSP directive:
- Images: Add to `img-src`
- Scripts: Add to `script-src`
- Styles: Add to `style-src`
- API calls: Add to `connect-src`
## Environment Parity
**Development** and **Production** should match as closely as possible:
| Environment | Dev Server | CSP Enabled | Use Case |
|-------------|-----------|-------------|----------|
| `npm run dev` | Astro | ❌ No | Fast development |
| `npm run dev:prod` | Express | ✅ Yes | Pre-deployment testing |
| Docker (production) | Express | ✅ Yes | Production |
## Docker Testing (Optional)
To test the **exact** Docker environment locally:
```bash
# Build the Docker image
docker build -t 365devnet-test .
# Run it locally
docker run -p 3000:3000 -e ENABLE_SSR_CSP=1 365devnet-test
# Visit http://localhost:3000
```
## Continuous Integration (CI)
Consider adding these checks to your CI pipeline:
```yaml
# .github/workflows/test.yml (example)
- name: Build
run: npm run build
- name: Test with CSP
run: |
ENABLE_SSR_CSP=1 npm run start &
sleep 5
curl -f http://localhost:3000 || exit 1
```
## Best Practices
1. **Always test with `dev:prod` before deploying**
2. Check browser console for errors
3. Test interactive features manually
4. Keep development and production environments in sync
5. Document any CSP changes in `server.js`
6. Update this checklist as new features are added
## Troubleshooting
**Q: CSP is too restrictive, breaking features**
**A:** Carefully add specific domains/directives instead of disabling CSP entirely
**Q: Need to temporarily disable CSP for testing**
**A:** Run without `ENABLE_SSR_CSP=1`: `npm run start`
**Q: CSP works locally but not in Docker**
**A:** Check `docker-compose.yml` - ensure `ENABLE_SSR_CSP=1` is set
---
**Remember:** Security settings that don't work in production are useless. Test early, test often! 🛡️