145 lines
2.8 KiB
Markdown
145 lines
2.8 KiB
Markdown
# Troubleshooting Guide
|
|
|
|
## Common Issues and Solutions
|
|
|
|
### "Browser not found" / "Executable doesn't exist"
|
|
|
|
**Cause**: Playwright browsers not installed.
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Install browsers
|
|
playwright install chromium
|
|
|
|
# Or install all browsers
|
|
playwright install
|
|
```
|
|
|
|
### "Command not found: playwright"
|
|
|
|
**Cause**: Playwright not installed globally.
|
|
|
|
**Solutions**:
|
|
```bash
|
|
# Option 1: Install globally
|
|
npm install -g playwright
|
|
|
|
# Option 2: Use via npx (no install needed)
|
|
npx playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
|
|
```
|
|
|
|
### Blank or White Image
|
|
|
|
**Cause**: File path not resolving correctly.
|
|
|
|
**Debug**:
|
|
```bash
|
|
# Check the file exists
|
|
ls -la diagram.html
|
|
|
|
# Check URL format (should be file://...)
|
|
echo "file://$(pwd)/diagram.html"
|
|
```
|
|
|
|
**Solution**: Ensure using `file://` protocol with absolute path.
|
|
|
|
### Image is 800x600 (Viewport Only)
|
|
|
|
**Cause**: Missing `--full-page` flag.
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Add --full-page flag
|
|
playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
|
|
```
|
|
|
|
### Missing Images/CSS in Output
|
|
|
|
**Cause**: HTML uses relative paths that don't resolve in file:// context.
|
|
|
|
**Solutions**:
|
|
|
|
1. **Use absolute paths in HTML**:
|
|
```html
|
|
<!-- Instead of -->
|
|
<img src="images/logo.png">
|
|
<!-- Use -->
|
|
<img src="file:///Users/you/project/images/logo.png">
|
|
```
|
|
|
|
2. **Embed images as base64**:
|
|
```html
|
|
<img src="data:image/png;base64,iVBORw0KGgoAAAANS...">
|
|
```
|
|
|
|
3. **Inline CSS**:
|
|
```html
|
|
<style>
|
|
/* CSS inline instead of <link> */
|
|
</style>
|
|
```
|
|
|
|
### Fonts Not Rendering
|
|
|
|
**Cause**: Web fonts not loading in file:// context.
|
|
|
|
**Solutions**:
|
|
|
|
1. Use system fonts:
|
|
```css
|
|
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
|
|
```
|
|
|
|
2. Embed fonts as base64 in CSS.
|
|
|
|
### Slow Conversion
|
|
|
|
**Cause**: Browser startup overhead or large content.
|
|
|
|
**Solutions**:
|
|
```bash
|
|
# For batch operations, reuse browser (requires script)
|
|
# For single operations, ~3-5 seconds is normal
|
|
|
|
# If content is dynamic, reduce wait time
|
|
playwright screenshot --full-page --wait-for-timeout=500 "file://$(pwd)/diagram.html" output.png
|
|
```
|
|
|
|
### Permission Denied
|
|
|
|
**Cause**: Cannot write to output directory.
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Check directory permissions
|
|
ls -la $(dirname output.png)
|
|
|
|
# Create directory if needed
|
|
mkdir -p docs/images
|
|
```
|
|
|
|
### Fuzzy/Blurry Text
|
|
|
|
**Cause**: Low DPI capture.
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Use 2x scale for retina-quality output
|
|
playwright screenshot --full-page --scale=2 "file://$(pwd)/diagram.html" output.png
|
|
```
|
|
|
|
## Debug Mode
|
|
|
|
For detailed troubleshooting:
|
|
|
|
```bash
|
|
# Enable debug output
|
|
DEBUG=pw:api playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
|
|
```
|
|
|
|
## Getting Help
|
|
|
|
1. Check Playwright docs: https://playwright.dev/docs/cli
|
|
2. Verify HTML renders in browser: `open diagram.html`
|
|
3. Test with simple HTML first to isolate issue
|