Richard Bergsma
db6270438f
- 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.
133 lines
3.5 KiB
Markdown
133 lines
3.5 KiB
Markdown
# 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! 🛡️
|
|
|