playwright-deblock

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