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:
132
TESTING.md
Normal file
132
TESTING.md
Normal 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! 🛡️
|
||||
|
||||
Reference in New Issue
Block a user