playwright-deblock

Automatic fix for Playwright file:// navigation blocks. One require(), works forever.

Problem

Restricted Playwright runners block file:// URLs:

Access to 'file:' URL is blocked. Allowed protocols: http, https, about, data.

Solution

npm install playwright-deblock

require("playwright-deblock");

Done. Every page.goto("file://...") is now automatically served over http://localhost.

Usage

Auto-patch (recommended)

// Add this ONE line at the top of your script or test
require("playwright-deblock");

// Then use file:// like normal — it just works
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("file:///home/user/page.html"); // auto-redirected to http://

Playwright config (global)

// playwright.config.js
module.exports = {
  globalSetup: require.resolve("playwright-deblock/register"),
};

Or via CLI:

npx playwright test --require playwright-deblock/register

With options

const deblock = require("playwright-deblock");
deblock.apply({ strategy: "data", silent: true });

Manual helper (no monkey-patching)

const { serveAndGoto, cleanup } = require("playwright-deblock/helper");

test("loads local HTML", async ({ page }) => {
  await serveAndGoto(page, "/path/to/file.html");
  await expect(page.locator("h1")).toBeVisible();
});

test.afterAll(() => cleanup());

How it works

| Strategy | Protocol | Method | |---|---|---| | http (primary) | http:// | Starts localhost server, serves the file's directory | | data (fallback) | data: | Inlines CSS/JS/images into a data: URL |

• Original HTML files are never modified on disk
• One server per directory, reused across calls
• Servers auto-cleanup on process exit
• Works with chromium, firefox, webkit
• Works with playwright and playwright-core

API

| Export | Description | |---|---| | apply(opts?) | Re-apply patch with options | | cleanup() | Stop all HTTP servers | | convertUrl(url) | Convert a file:// URL manually | | serveAndGoto(page, path) | Navigate without monkey-patching | | buildDataUrl(path) | Build a data: URL from HTML file | | inlineAssets(path) | Inline assets into HTML string |

License

MIT