A Playwright wrapper for the Effect ecosystem. This library provides a set of services and layers to interact with Playwright in a type-safe way using Effect.
Playwright Test Integration is also supported.
pnpm add effect-playwright
pnpm effect-playwright install chromiumBrowser installation is not required if connecting to an existing browser via CDP or using a local browser.
import { Playwright, chromium } from "effect-playwright";
import { Effect } from "effect";
const program = Effect.gen(function* () {
const playwright = yield* Playwright;
const browser = yield* playwright.launchScoped(chromium);
const page = yield* browser.newPage();
yield* page.goto("https://example.com");
const title = yield* page.title;
yield* Effect.log(`Page title: ${title}`);
}).pipe(Effect.scoped, Effect.provide(Playwright.layer));
await Effect.runPromise(program);Using launchScoped is the recommended way to manage the browser lifecycle. It ensures that the browser is closed automatically when the effect's scope ends, preventing resource leaks.
const program = Effect.gen(function* () {
const playwright = yield* Playwright;
const browser = yield* playwright.launchScoped(chromium);
// Browser will be closed automatically after this block
}).pipe(Effect.scoped);You can connect to an existing browser instance using the Chrome DevTools Protocol (CDP).
const program = Effect.gen(function* () {
const playwright = yield* Playwright;
// Use connectCDPScoped to automatically close the CONNECTION when the scope ends
// Note: This does NOT close the browser process itself, only the CDP connection.
const browser = yield* playwright.connectCDPScoped("http://localhost:9222");
const page = yield* browser.newPage();
// ...
}).pipe(Effect.scoped);If you need to manage the connection lifecycle manually, use connectCDP:
const program = Effect.gen(function* () {
const playwright = yield* Playwright;
const browser = yield* playwright.connectCDP("http://localhost:9222");
// ... use browser ...
yield* browser.close;
});The PlaywrightEnvironment simplifies setup by allowing you to configure the browser type and launch options once and reuse them across your application.
import { PlaywrightBrowser, chromium } from "effect-playwright";
import { PlaywrightEnvironment } from "effect-playwright/experimental";
import { Effect } from "effect";
const liveLayer = PlaywrightEnvironment.layer(chromium, {
headless: false /** any other launch options */,
});
const program = Effect.gen(function* () {
const browser = yield* PlaywrightBrowser;
const page = yield* browser.newPage();
yield* page.goto("https://example.com");
}).pipe(PlaywrightEnvironment.withBrowser);
await Effect.runPromise(program.pipe(Effect.provide(liveLayer)));The withBrowser utility provides the PlaywrightBrowser service to your effect. It internally manages a Scope, which means the browser will be launched when the effect starts and closed automatically when the effect finishes (including on failure or interruption).
const program = Effect.gen(function* () {
const browser = yield* PlaywrightBrowser; // Now available in context
const page = yield* browser.newPage();
// ...
// Browser close is ensured
}).pipe(PlaywrightEnvironment.withBrowser);You can listen to Playwright events using the eventStream method. This returns an Effect Stream that emits events as they occur.
Note
eventStream emits "Effectified" wrappers (e.g., PlaywrightRequest, PlaywrightResponse, PlaywrightPage) for most events. This allows you to continue using the Effect ecosystem seamlessly within your event handlers.
The stream is automatically managed and will close when the underlying resource (like the Page or Browser) is closed.
Since event streams run indefinitely until the resource closes, you often need to fork the resulting effect so it runs in the background without blocking your main program flow.
const program = Effect.gen(function* () {
const browser = yield* PlaywrightBrowser;
const page = yield* browser.newPage();
// Create a stream of request events
yield* page.eventStream("request").pipe(
Stream.runForEach((request) =>
Effect.gen(function* () {
yield* Effect.log(`Request: ${request.url()}`);
}),
),
// Fork to run it in the background
Effect.fork,
);
yield* page.goto("https://example.com");
}).pipe(PlaywrightEnvironment.withBrowser);If you need to access functionality from the underlying Playwright objects that isn't directly exposed, you can use the use method available on most services/objects (browsers, pages, locators).
import { Playwright, chromium } from "effect-playwright";
import { Effect } from "effect";
const program = Effect.gen(function* () {
const playwright = yield* Playwright;
const browser = yield* playwright.launchScoped(chromium);
const page = yield* browser.newPage();
// Use the native Playwright Page object
const screenshot = yield* page.use((p) => p.screenshot());
});All methods return effects that can fail with a PlaywrightError. This error wraps the original error from Playwright.
Note that Playwright does not support interruption, so Effect.timeout or similar code does not behave like you
might expect. Playwright provides its own timeout option for almost every method.
effect-playwright includes a lightweight command-line wrapper that forwards all commands directly to the underlying playwright-core CLI. You can use it to install browsers, generate code, or inspect traces:
# Install browsers
pnpm effect-playwright install chromium
# Code generation
pnpm effect-playwright codegen https://example.com
# Open inspector / trace viewer
pnpm effect-playwright show-trace trace.zipInstall the optional Playwright Test peer dependency to use Effect programs in the upstream test runner:
pnpm add -D @playwright/test effect-playwrightimport { Effect } from "effect";
import { PlaywrightPage } from "effect-playwright";
import { expect, test } from "effect-playwright/test";
test.effect("shows the example.com headline", () =>
Effect.gen(function* () {
const page = yield* PlaywrightPage;
yield* page.goto("https://example.com");
const headline = page.getByRole("heading", { name: "Example Domain" });
expect(yield* headline.innerText()).toBe("Example Domain");
}),
);test.effect runs each Effect in a scope, so acquired resources are released when the test finishes, fails, or times out:
import { Effect } from "effect";
import { test } from "effect-playwright/test";
test.effect("cleans up after the test", () =>
Effect.acquireRelease(Effect.log("Creating User"), () =>
Effect.log("Cleanup: Deleting user"),
),
);Effect scope finalizers run during test-scoped fixture teardown. On test timeout, this occurs after user afterEach.
Effect layers are the preferred way to provide dependencies to Effect-based
Playwright tests. Use layer to acquire a layer once per Playwright worker and
share it between the tests in a block. Layer finalizers run after every test in
the block has finished. Nested layers reuse their parent services.
import { Context, Effect, Layer } from "effect";
import { expect, layer } from "effect-playwright/test";
class Greeting extends Context.Tag("Greeting")<Greeting, string>() {}
layer(Layer.succeed(Greeting, "hello"))("Greeting", (it) => {
it.effect("uses a shared service", () =>
Effect.gen(function* () {
expect(yield* Greeting).toBe("hello");
}),
);
});Custom Playwright fixtures are supported mainly for compatibility with existing
Playwright Test suites. Prefer Effect layers.
When integration with an existing custom TestType is required, call
makeMethods after extending or merging it:
import { test as base } from "@playwright/test";
import { Effect } from "effect";
import { expect, makeMethods } from "effect-playwright/test";
const test = makeMethods(
base.extend<{ answer: number }>({
answer: async ({}, use) => use(42),
}),
);
test.effect("uses a custom fixture", ({ answer }) =>
Effect.sync(() => expect(answer).toBe(42)),
);