effect-playwright 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright 2025 Jobflow GmbH
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# effect-playwright
+
+[![GitHub License](https://img.shields.io/github/license/Jobflow-io/effect-playwright)](https://github.com/Jobflow-io/effect-playwright/blob/main/LICENSE)
+[![Effect: yes](https://img.shields.io/badge/effect-yes-blue)](https://effect.website/)
+
+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.
+
+## Installation
+
+```bash
+pnpm add effect-playwright playwright-core
+```
+
+or
+
+```bash
+npm install effect-playwright playwright-core
+```
+
+## Quick Start
+
+```ts
+import { Playwright } from "effect-playwright";
+import { Effect } from "effect";
+import { chromium } from "playwright-core";
+
+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;
+  console.log(`Page title: ${title}`);
+}).pipe(Effect.scoped, Effect.provide(Playwright.layer));
+
+await Effect.runPromise(program);
+```
+
+## Managing Lifecycle
+
+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.
+
+```ts
+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);
+```
+
+## PlaywrightEnvironment (Experimental)
+
+The `PlaywrightEnvironment` simplifies setup by allowing you to configure the browser type and launch options once and reuse them across your application.
+
+### Usage
+
+```ts
+import { PlaywrightBrowser } from "effect-playwright";
+import { PlaywrightEnvironment } from "effect-playwright/experimental";
+import { Effect } from "effect";
+import { chromium } from "playwright-core";
+
+const liveLayer = PlaywrightEnvironment.layer(chromium, {
+  headless: true /** 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)));
+```
+
+## Accessing Native Playwright
+
+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).
+
+```ts
+import { Playwright } from "effect-playwright";
+import { Effect } from "effect";
+import { chromium } from "playwright-core";
+
+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());
+});
+```
+
+## Error Handling
+
+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.

package/dist/chunk-BiucMVzj.mjs

@@ -0,0 +1,18 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll as t };

package/dist/experimental/index.d.mts

@@ -0,0 +1,74 @@
+import { d as PlaywrightError, o as PlaywrightBrowser } from "../index-aR0Fa_4Y.mjs";
+import { Context, Effect, Layer } from "effect";
+import { BrowserType, LaunchOptions } from "playwright-core";
+import { Scope as Scope$1 } from "effect/Scope";
+
+//#region src/experimental/environment.d.ts
+declare namespace environment_d_exports {
+  export { PlaywrightEnvironment, layer, withBrowser };
+}
+declare const PlaywrightEnvironment_base: Context.TagClass<PlaywrightEnvironment, "effect-playwright/experimental/PlaywrightEnvironment", {
+  browser: Effect.Effect<typeof PlaywrightBrowser.Service, PlaywrightError, Scope$1>;
+}>;
+/**
+ * Most of the time you want to use the same kind of browser and configuration every time you use Playwright.
+ * `PlaywrightEnvironment` is a service that allows you to configure how browsers are launched once. You can then
+ * use {@link PlaywrightEnvironment.browser} to start browsers scoped to the current lifetime. They will be closed when the scope is closed.
+ *
+ * You can use {@link PlaywrightEnvironment.withBrowser} to provide the `PlaywrightBrowser` service to the wrapped effect. This
+ * also allows you to re-use the same browser as many times as you want.
+ *
+ * @since 0.1.0
+ * @category tag
+ */
+declare class PlaywrightEnvironment extends PlaywrightEnvironment_base {}
+/**
+ * Creates a Layer that initializes the `PlaywrightEnvironment`.
+ *
+ * @example
+ *
+ * ```ts
+ * import { PlaywrightEnvironment } from "effect-playwright/experimental";
+ * import { chromium } from "playwright-core";
+ *
+ * const playwrightEnv = PlaywrightEnvironment.layer(chromium);
+ *
+ * // use the layer
+ * const program = Effect.gen(function* () {
+ *   const browser = yield* PlaywrightEnvironment.browser;
+ *   const page = yield* browser.newPage();
+ *   yield* page.goto("https://example.com");
+ * }).pipe(PlaywrightEnvironment.withBrowser, Effect.provide(playwrightEnv));
+ * ```
+ *
+ * @param browser - The Playwright BrowserType implementation (e.g. `chromium`, `firefox`, `webkit`).
+ * @param launchOptions - Optional configuration for launching the browser (e.g. headless, args).
+ *
+ * @since 0.1.0
+ * @category layer
+ */
+declare const layer: (browser: BrowserType, launchOptions?: LaunchOptions) => Layer.Layer<PlaywrightEnvironment, never, never>;
+/**
+ * Provides a scoped `PlaywrightBrowser` service, allowing you to access the browser from the context (e.g. by yielding `PlaywrightBrowser`).
+ *
+ * You will need to provide the `PlaywrightEnvironment` layer first.
+ *
+ * @example
+ *
+ * ```ts
+ * import { PlaywrightEnvironment } from "effect-playwright/experimental";
+ * import { chromium } from "playwright-core";
+ *
+ * const layer = PlaywrightEnvironment.layer(chromium);
+ * const program = Effect.gen(function* () {
+ *     const browser = yield* PlaywrightBrowser;
+ *     const page = yield* browser.newPage();
+ *     yield* page.goto("https://example.com");
+ * }).pipe(PlaywrightEnvironment.withBrowser);
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare const withBrowser: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, PlaywrightError | E, PlaywrightEnvironment | Exclude<R, PlaywrightBrowser>>;
+//#endregion
+export { environment_d_exports as PlaywrightEnvironment };

package/dist/experimental/index.mjs

@@ -0,0 +1,77 @@
+import { t as __exportAll } from "../chunk-BiucMVzj.mjs";
+import { n as PlaywrightBrowser, t as Playwright } from "../src-DveiwW4g.mjs";
+import { Context, Effect, Layer } from "effect";
+
+//#region src/experimental/environment.ts
+var environment_exports = /* @__PURE__ */ __exportAll({
+	PlaywrightEnvironment: () => PlaywrightEnvironment,
+	layer: () => layer,
+	withBrowser: () => withBrowser
+});
+/**
+* Most of the time you want to use the same kind of browser and configuration every time you use Playwright.
+* `PlaywrightEnvironment` is a service that allows you to configure how browsers are launched once. You can then
+* use {@link PlaywrightEnvironment.browser} to start browsers scoped to the current lifetime. They will be closed when the scope is closed.
+*
+* You can use {@link PlaywrightEnvironment.withBrowser} to provide the `PlaywrightBrowser` service to the wrapped effect. This
+* also allows you to re-use the same browser as many times as you want.
+*
+* @since 0.1.0
+* @category tag
+*/
+var PlaywrightEnvironment = class extends Context.Tag("effect-playwright/experimental/PlaywrightEnvironment")() {};
+/**
+* Creates a Layer that initializes the `PlaywrightEnvironment`.
+*
+* @example
+*
+* ```ts
+* import { PlaywrightEnvironment } from "effect-playwright/experimental";
+* import { chromium } from "playwright-core";
+*
+* const playwrightEnv = PlaywrightEnvironment.layer(chromium);
+*
+* // use the layer
+* const program = Effect.gen(function* () {
+*   const browser = yield* PlaywrightEnvironment.browser;
+*   const page = yield* browser.newPage();
+*   yield* page.goto("https://example.com");
+* }).pipe(PlaywrightEnvironment.withBrowser, Effect.provide(playwrightEnv));
+* ```
+*
+* @param browser - The Playwright BrowserType implementation (e.g. `chromium`, `firefox`, `webkit`).
+* @param launchOptions - Optional configuration for launching the browser (e.g. headless, args).
+*
+* @since 0.1.0
+* @category layer
+*/
+const layer = (browser, launchOptions) => {
+	return Layer.effect(PlaywrightEnvironment, Playwright.pipe(Effect.map((playwright) => {
+		return PlaywrightEnvironment.of({ browser: playwright.launchScoped(browser, launchOptions) });
+	})).pipe(Effect.provide(Playwright.layer)));
+};
+/**
+* Provides a scoped `PlaywrightBrowser` service, allowing you to access the browser from the context (e.g. by yielding `PlaywrightBrowser`).
+*
+* You will need to provide the `PlaywrightEnvironment` layer first.
+*
+* @example
+*
+* ```ts
+* import { PlaywrightEnvironment } from "effect-playwright/experimental";
+* import { chromium } from "playwright-core";
+*
+* const layer = PlaywrightEnvironment.layer(chromium);
+* const program = Effect.gen(function* () {
+*     const browser = yield* PlaywrightBrowser;
+*     const page = yield* browser.newPage();
+*     yield* page.goto("https://example.com");
+* }).pipe(PlaywrightEnvironment.withBrowser);
+* ```
+*
+* @since 0.1.0
+*/
+const withBrowser = Effect.provide(PlaywrightEnvironment.pipe(Effect.map((e) => e.browser), Effect.flatten, Layer.scoped(PlaywrightBrowser)));
+
+//#endregion
+export { environment_exports as PlaywrightEnvironment };

package/dist/index-aR0Fa_4Y.d.mts

@@ -0,0 +1,584 @@
+import { Context, Effect, Layer, Scope, Stream } from "effect";
+import { Browser, BrowserContext, BrowserType, ConnectOverCDPOptions, ConsoleMessage, Dialog, Download, ElementHandle, FileChooser, Frame, JSHandle, Locator, Page, Request, Response, WebSocket, Worker, chromium } from "playwright-core";
+import { Scope as Scope$1 } from "effect/Scope";
+import * as effect_Types0 from "effect/Types";
+import * as effect_Cause0 from "effect/Cause";
+
+//#region src/errors.d.ts
+type PlaywrightErrorReason = "Timeout" | "Unknown";
+declare const PlaywrightError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "PlaywrightError";
+} & Readonly<A>;
+declare class PlaywrightError extends PlaywrightError_base<{
+  reason: PlaywrightErrorReason;
+  cause: unknown;
+}> {}
+//#endregion
+//#region src/playwright-types.d.ts
+/**
+ * Extracted from `playwright-core/types/structs.d.ts` because it is not exported over the package boundary.
+ * These types are necessary to correctly type `evaluate` functions that unwrap handles.
+ */
+type NoHandles<Arg> = Arg extends JSHandle ? never : Arg extends object ? { [Key in keyof Arg]: NoHandles<Arg[Key]> } : Arg;
+type Unboxed<Arg> = Arg extends ElementHandle<infer T> ? T : Arg extends JSHandle<infer T> ? T : Arg extends NoHandles<Arg> ? Arg : Arg extends [infer A0] ? [Unboxed<A0>] : Arg extends [infer A0, infer A1] ? [Unboxed<A0>, Unboxed<A1>] : Arg extends [infer A0, infer A1, infer A2] ? [Unboxed<A0>, Unboxed<A1>, Unboxed<A2>] : Arg extends [infer A0, infer A1, infer A2, infer A3] ? [Unboxed<A0>, Unboxed<A1>, Unboxed<A2>, Unboxed<A3>] : Arg extends Array<infer T> ? Array<Unboxed<T>> : Arg extends object ? { [Key in keyof Arg]: Unboxed<Arg[Key]> } : Arg;
+type PageFunction<Arg, R> = string | ((arg: Unboxed<Arg>) => R | Promise<R>);
+//#endregion
+//#region src/locator.d.ts
+/**
+ * Interface for a Playwright locator.
+ * @category model
+ */
+interface PlaywrightLocatorService {
+  /**
+   * Clicks the element.
+   *
+   * @see {@link Locator.click}
+   * @since 0.1.0
+   */
+  readonly click: (options?: Parameters<Locator["click"]>[0]) => Effect.Effect<void, PlaywrightError>;
+  /**
+   * Fills the input field.
+   *
+   * @see {@link Locator.fill}
+   * @since 0.1.0
+   */
+  readonly fill: (value: string, options?: Parameters<Locator["fill"]>[1]) => Effect.Effect<void, PlaywrightError>;
+  /**
+   * Gets an attribute value.
+   *
+   * @see {@link Locator.getAttribute}
+   * @since 0.1.0
+   */
+  readonly getAttribute: (name: string, options?: Parameters<Locator["getAttribute"]>[1]) => Effect.Effect<string | null, PlaywrightError>;
+  /**
+   * Gets the inner text.
+   *
+   * @see {@link Locator.innerText}
+   * @since 0.1.0
+   */
+  readonly innerText: (options?: Parameters<Locator["innerText"]>[0]) => Effect.Effect<string, PlaywrightError>;
+  /**
+   * Gets the inner HTML.
+   *
+   * @see {@link Locator.innerHTML}
+   * @since 0.1.0
+   */
+  readonly innerHTML: (options?: Parameters<Locator["innerHTML"]>[0]) => Effect.Effect<string, PlaywrightError>;
+  /**
+   * Gets the input value.
+   *
+   * @see {@link Locator.inputValue}
+   * @since 0.1.0
+   */
+  readonly inputValue: (options?: Parameters<Locator["inputValue"]>[0]) => Effect.Effect<string, PlaywrightError>;
+  /**
+   * Gets the text content.
+   *
+   * @see {@link Locator.textContent}
+   * @since 0.1.0
+   */
+  readonly textContent: (options?: Parameters<Locator["textContent"]>[0]) => Effect.Effect<string | null, PlaywrightError>;
+  /**
+   * Counts the number of matched elements.
+   *
+   * @see {@link Locator.count}
+   * @since 0.1.0
+   */
+  readonly count: Effect.Effect<number, PlaywrightError>;
+  /**
+   * Returns a locator that points to the first matched element.
+   * @see {@link Locator.first}
+   * @since 0.1.0
+   */
+  readonly first: () => PlaywrightLocatorService;
+  /**
+   * Returns a locator that points to the last matched element.
+   *
+   * @see {@link Locator.last}
+   * @since 0.1.0
+   */
+  readonly last: () => PlaywrightLocatorService;
+  /**
+   * Returns a locator that points to the nth matched element.
+   *
+   * @see {@link Locator.nth}
+   * @since 0.1.0
+   */
+  readonly nth: (index: number) => PlaywrightLocatorService;
+  /**
+   * Evaluates a function on the matched element.
+   *
+   * @example
+   * ```ts
+   * import { PlaywrightBrowser } from "effect-playwright";
+   * import { PlaywrightEnvironment } from "effect-playwright/experimental";
+   * import { chromium } from "@playwright/test";
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   *   const browser = yield* PlaywrightBrowser;
+   *   const page = yield* browser.newPage();
+   *   const locator = yield* page.locator("button");
+   *   const buttonContent = yield* locator.evaluate((button) => button.textContent());
+   * }).pipe(PlaywrightEnvironment.provideBrowser, Effect.provide(PlaywrightEnvironment.layer(chromium)));
+   * ```
+   *
+   * @see {@link Locator.evaluate}
+   * @since 0.1.0
+   */
+  readonly evaluate: <R, Arg = void, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: (element: E, arg: Unboxed<Arg>) => R | Promise<R>, arg?: Arg, options?: {
+    timeout?: number;
+  }) => Effect.Effect<R, PlaywrightError>;
+  /**
+   * A generic utility to execute any promise-based method on the underlying Playwright `Locator`.
+   * Can be used to access any Locator functionality not directly exposed by this service.
+   *
+   * @example
+   * ```typescript
+   * const isVisible = yield* locator.use((l) => l.isVisible());
+   * ```
+   *
+   * @param f - A function that takes the Playwright `Locator` and returns a `Promise`.
+   * @returns An effect that wraps the promise and returns its result.
+   * @see {@link Locator}
+   * @since 0.1.0
+   */
+  readonly use: <T$1>(f: (locator: Locator) => Promise<T$1>) => Effect.Effect<T$1, PlaywrightError>;
+}
+declare const PlaywrightLocator_base: Context.TagClass<PlaywrightLocator, "effect-playwright/PlaywrightLocator", PlaywrightLocatorService>;
+/**
+ * A service that provides a `PlaywrightLocator` instance.
+ *
+ * @since 0.1.0
+ * @category tag
+ */
+declare class PlaywrightLocator extends PlaywrightLocator_base {
+  /**
+   * Creates a `PlaywrightLocator` from a Playwright `Locator` instance. This is mostly for internal use.
+   * But you could use this if you have used `use` or similar to wrap the locator.
+   *
+   * @example
+   * ```ts
+   * const playwrightNativeLocator = yield* page.use((p) => p.locator("button"));
+   * const locator = PlaywrightLocator.make(playwrightNativeLocator);
+   * ```
+   *
+   * @param locator - The Playwright `Locator` instance to wrap.
+   * @since 0.1.0
+   * @category constructor
+   */
+  static make(locator: Locator): typeof PlaywrightLocator.Service;
+}
+//#endregion
+//#region src/page.d.ts
+interface PlaywrightPageEvents {
+  close: Page;
+  console: ConsoleMessage;
+  crash: Page;
+  dialog: Dialog;
+  domcontentloaded: Page;
+  download: Download;
+  filechooser: FileChooser;
+  frameattached: Frame;
+  framedetached: Frame;
+  framenavigated: Frame;
+  load: Page;
+  pageerror: Error;
+  popup: Page;
+  request: Request;
+  requestfailed: Request;
+  requestfinished: Request;
+  response: Response;
+  websocket: WebSocket;
+  worker: Worker;
+}
+interface PlaywrightPageService {
+  /**
+   * Navigates the page to the given URL.
+   *
+   * @example
+   * ```ts
+   * yield* page.goto("https://google.com");
+   * ```
+   *
+   * @see {@link Page.goto}
+   * @since 0.1.0
+   */
+  readonly goto: (url: string, options?: Parameters<Page["goto"]>[1]) => Effect.Effect<void, PlaywrightError>;
+  /**
+   * Waits for the page to navigate to the given URL.
+   *
+   * @example
+   * ```ts
+   * yield* page.waitForURL("https://google.com");
+   * ```
+   *
+   * @see {@link Page.waitForURL}
+   * @since 0.1.0
+   */
+  readonly waitForURL: (url: Parameters<Page["waitForURL"]>[0], options?: Parameters<Page["waitForURL"]>[1]) => Effect.Effect<void, PlaywrightError>;
+  /**
+   * Evaluates a function in the context of the page.
+   *
+   * @example
+   * ```ts
+   * const dimensions = yield* page.evaluate(() => ({
+   *   width: document.documentElement.clientWidth,
+   *   height: document.documentElement.clientHeight
+   * }));
+   * ```
+   *
+   * @see {@link Page.evaluate}
+   * @since 0.1.0
+   */
+  readonly evaluate: <R, Arg = void>(pageFunction: PageFunction<Arg, R>, arg?: Arg) => Effect.Effect<R, PlaywrightError>;
+  /**
+   * Returns the page title.
+   *
+   * @example
+   * ```ts
+   * const title = yield* page.title;
+   * ```
+   *
+   * @see {@link Page.title}
+   * @since 0.1.0
+   */
+  readonly title: Effect.Effect<string, PlaywrightError>;
+  /**
+   * A generic utility to execute any promise-based method on the underlying Playwright `Page`.
+   * Can be used to access any Page functionality not directly exposed by this service.
+   *
+   * @example
+   * ```ts
+   * const title = yield* page.use((p) => p.title());
+   * ```
+   *
+   * @see {@link Page}
+   * @since 0.1.0
+   */
+  readonly use: <T$1>(f: (page: Page) => Promise<T$1>) => Effect.Effect<T$1, PlaywrightError>;
+  /**
+   * Returns a locator for the given selector.
+   *
+   * @see {@link Page.locator}
+   * @since 0.1.0
+   */
+  readonly locator: (selector: string, options?: Parameters<Page["locator"]>[1]) => typeof PlaywrightLocator.Service;
+  /**
+   * Returns a locator that matches the given role.
+   *
+   * @see {@link Page.getByRole}
+   * @since 0.1.0
+   */
+  readonly getByRole: (role: Parameters<Page["getByRole"]>[0], options?: Parameters<Page["getByRole"]>[1]) => typeof PlaywrightLocator.Service;
+  /**
+   * Returns a locator that matches the given text.
+   *
+   * @see {@link Page.getByText}
+   * @since 0.1.0
+   */
+  readonly getByText: (text: Parameters<Page["getByText"]>[0], options?: Parameters<Page["getByText"]>[1]) => typeof PlaywrightLocator.Service;
+  /**
+   * Returns a locator that matches the given label.
+   *
+   * @see {@link Page.getByLabel}
+   * @since 0.1.0
+   */
+  readonly getByLabel: (label: Parameters<Page["getByLabel"]>[0], options?: Parameters<Page["getByLabel"]>[1]) => typeof PlaywrightLocator.Service;
+  /**
+   * Returns a locator that matches the given test id.
+   *
+   * @see {@link Page.getByTestId}
+   * @since 0.1.0
+   */
+  readonly getByTestId: (testId: Parameters<Page["getByTestId"]>[0]) => typeof PlaywrightLocator.Service;
+  /**
+   * Reloads the page.
+   *
+   * @see {@link Page.reload}
+   * @since 0.1.0
+   */
+  readonly reload: Effect.Effect<void, PlaywrightError>;
+  /**
+   * Closes the page.
+   *
+   * @see {@link Page.close}
+   * @since 0.1.0
+   */
+  readonly close: Effect.Effect<void, PlaywrightError>;
+  /**
+   * Returns the current URL of the page.
+   *
+   * @example
+   * ```ts
+   * const url = yield* page.url;
+   * ```
+   *
+   * @see {@link Page.url}
+   * @since 0.1.0
+   */
+  readonly url: Effect.Effect<string, PlaywrightError>;
+  /**
+   * Creates a stream of the given event from the page.
+   *
+   * @example
+   * ```ts
+   * const consoleStream = page.eventStream("console");
+   * ```
+   *
+   * @see {@link Page.on}
+   * @since 0.1.0
+   */
+  readonly eventStream: <K extends keyof PlaywrightPageEvents>(event: K) => Stream.Stream<PlaywrightPageEvents[K]>;
+  /**
+   * Clicks an element matching the given selector.
+   *
+   * @example
+   * ```ts
+   * yield* page.click("button#submit");
+   * ```
+   * @deprecated Use {@link PlaywrightPageService.locator} to create a locator and then call `click` on it instead.
+   * @see {@link Page.click}
+   * @since 0.1.0
+   * @category deprecated
+   */
+  readonly click: (selector: string, options?: Parameters<Page["click"]>[1]) => Effect.Effect<void, PlaywrightError>;
+}
+declare const PlaywrightPage_base: Context.TagClass<PlaywrightPage, "effect-playwright/PlaywrightPage", PlaywrightPageService>;
+/**
+ * @category tag
+ */
+declare class PlaywrightPage extends PlaywrightPage_base {
+  /**
+   * Creates a `PlaywrightPage` from a Playwright `Page` instance.
+   *
+   * @param page - The Playwright `Page` instance to wrap.
+   * @since 0.1.0
+   */
+  static make(page: Page): PlaywrightPageService;
+}
+//#endregion
+//#region src/browser-context.d.ts
+declare const PlaywrightBrowserContext_base: Context.TagClass<PlaywrightBrowserContext, "cehs/backend/lib/playwright/PlaywrightBrowserContext", {
+  readonly pages: Effect.Effect<Array<typeof PlaywrightPage.Service>>;
+  readonly newPage: Effect.Effect<typeof PlaywrightPage.Service, PlaywrightError>;
+  readonly close: Effect.Effect<void, PlaywrightError>;
+}>;
+declare class PlaywrightBrowserContext extends PlaywrightBrowserContext_base {
+  static make(context: BrowserContext): {
+    readonly pages: Effect.Effect<Array<typeof PlaywrightPage.Service>>;
+    readonly newPage: Effect.Effect<typeof PlaywrightPage.Service, PlaywrightError>;
+    readonly close: Effect.Effect<void, PlaywrightError>;
+  };
+}
+//#endregion
+//#region src/browser.d.ts
+type LaunchOptions$1 = Parameters<typeof chromium.launch>[0];
+type NewPageOptions = Parameters<Browser["newPage"]>[0];
+type NewContextOptions = Parameters<Browser["newContext"]>[0];
+declare const PlaywrightBrowser_base: Context.TagClass<PlaywrightBrowser, "cehs/backend/lib/playwright/PlaywrightBrowser", {
+  /**
+   * Opens a new page in the browser.
+   *
+   * @example
+   * ```typescript
+   * const page = yield* browser.newPage();
+   * ```
+   *
+   * @param options - Optional options for creating the new page.
+   * @returns An effect that resolves to a `PlaywrightPage` service.
+   * @see {@link Browser.newPage}
+   */
+  readonly newPage: (options?: NewPageOptions) => Effect.Effect<typeof PlaywrightPage.Service, PlaywrightError>;
+  /**
+   * A generic utility to execute any promise-based method on the underlying Playwright `Browser`.
+   * Can be used to access any Browser functionality not directly exposed by this service.
+   *
+   * @example
+   * ```typescript
+   * const contexts = yield* browser.use((b) => b.contexts());
+   * ```
+   *
+   * @param f - A function that takes the Playwright `Browser` and returns a `Promise`.
+   * @returns An effect that wraps the promise and returns its result.
+   * @see {@link Browser}
+   */
+  readonly use: <T$1>(f: (browser: Browser) => Promise<T$1>) => Effect.Effect<T$1, PlaywrightError>;
+  /**
+   * An Effect that closes the browser and all of its pages.
+   * @see {@link Browser.close}
+   */
+  readonly close: Effect.Effect<void, PlaywrightError>;
+  /**
+   * An Effect that returns the list of all open browser contexts.
+   * @see {@link Browser.contexts}
+   */
+  readonly contexts: Effect.Effect<Array<typeof PlaywrightBrowserContext.Service>>;
+  readonly newContext: (options?: NewContextOptions) => Effect.Effect<typeof PlaywrightBrowserContext.Service, PlaywrightError, Scope$1>;
+  /**
+   * An Effect that returns the browser type (chromium, firefox or webkit) that the browser belongs to.
+   * @see {@link Browser.browserType}
+   */
+  readonly browserType: Effect.Effect<BrowserType>;
+  /**
+   * An Effect that returns the version of the browser.
+   * @see {@link Browser.version}
+   */
+  readonly version: Effect.Effect<string>;
+  /**
+   * An Effect that returns whether the browser is connected.
+   * @see {@link Browser.isConnected}
+   */
+  readonly isConnected: Effect.Effect<boolean>;
+}>;
+/**
+ * @category tag
+ */
+declare class PlaywrightBrowser extends PlaywrightBrowser_base {
+  /**
+   * @category constructor
+   */
+  static make(browser: Browser): {
+    /**
+     * Opens a new page in the browser.
+     *
+     * @example
+     * ```typescript
+     * const page = yield* browser.newPage();
+     * ```
+     *
+     * @param options - Optional options for creating the new page.
+     * @returns An effect that resolves to a `PlaywrightPage` service.
+     * @see {@link Browser.newPage}
+     */
+    readonly newPage: (options?: NewPageOptions) => Effect.Effect<typeof PlaywrightPage.Service, PlaywrightError>;
+    /**
+     * A generic utility to execute any promise-based method on the underlying Playwright `Browser`.
+     * Can be used to access any Browser functionality not directly exposed by this service.
+     *
+     * @example
+     * ```typescript
+     * const contexts = yield* browser.use((b) => b.contexts());
+     * ```
+     *
+     * @param f - A function that takes the Playwright `Browser` and returns a `Promise`.
+     * @returns An effect that wraps the promise and returns its result.
+     * @see {@link Browser}
+     */
+    readonly use: <T$1>(f: (browser: Browser) => Promise<T$1>) => Effect.Effect<T$1, PlaywrightError>;
+    /**
+     * An Effect that closes the browser and all of its pages.
+     * @see {@link Browser.close}
+     */
+    readonly close: Effect.Effect<void, PlaywrightError>;
+    /**
+     * An Effect that returns the list of all open browser contexts.
+     * @see {@link Browser.contexts}
+     */
+    readonly contexts: Effect.Effect<Array<typeof PlaywrightBrowserContext.Service>>;
+    readonly newContext: (options?: NewContextOptions) => Effect.Effect<typeof PlaywrightBrowserContext.Service, PlaywrightError, Scope$1>;
+    /**
+     * An Effect that returns the browser type (chromium, firefox or webkit) that the browser belongs to.
+     * @see {@link Browser.browserType}
+     */
+    readonly browserType: Effect.Effect<BrowserType>;
+    /**
+     * An Effect that returns the version of the browser.
+     * @see {@link Browser.version}
+     */
+    readonly version: Effect.Effect<string>;
+    /**
+     * An Effect that returns whether the browser is connected.
+     * @see {@link Browser.isConnected}
+     */
+    readonly isConnected: Effect.Effect<boolean>;
+  };
+}
+//#endregion
+//#region src/playwright.d.ts
+interface PlaywrightService {
+  /**
+   * Launches a new browser instance.
+   *
+   * It is the caller's responsibility to manage the browser's lifecycle and close
+   * it when no longer needed. For automatic scope-based management, use
+   * {@link launchScoped} instead.
+   *
+   * ```ts
+   * import { Effect } from "effect";
+   * import { Playwright } from "effect-playwright";
+   * import { chromium } from "playwright-core";
+   *
+   * const program = Effect.gen(function* () {
+   *   const browser = yield* Playwright.launch(chromium);
+   *   // ... use browser ...
+   *   yield* browser.close;
+   * });
+   *
+   * await Effect.runPromise(program);
+   * ```
+   *
+   * @param browserType - The browser type to launch (e.g. chromium, firefox, webkit).
+   * @param options - Optional launch options.
+   * @since 0.1.0
+   */
+  launch: (browserType: BrowserType, options?: LaunchOptions$1) => Effect.Effect<typeof PlaywrightBrowser.Service, PlaywrightError>;
+  /**
+   * Launches a new browser instance managed by a Scope.
+   *
+   * This method automatically closes the browser when the scope is closed.
+   *
+   * ```ts
+   * import { Effect } from "effect";
+   * import { Playwright } from "effect-playwright";
+   * import { chromium } from "playwright-core";
+   *
+   * const program = Effect.gen(function* () {
+   *   const browser = yield* Playwright.launchScoped(chromium);
+   *   // Browser will be closed automatically when scope closes
+   * });
+   *
+   * await Effect.runPromise(program);
+   * ```
+   *
+   * @param browserType - The browser type to launch (e.g. chromium, firefox, webkit).
+   * @param options - Optional launch options.
+   * @since 0.1.0
+   */
+  launchScoped: (browserType: BrowserType, options?: LaunchOptions$1) => Effect.Effect<typeof PlaywrightBrowser.Service, PlaywrightError, Scope.Scope>;
+  /**
+   * Connects to a browser instance via Chrome DevTools Protocol (CDP).
+   *
+   * Unlike {@link launchScoped}, this method does **not** close the browser when the
+   * scope is closed. It is the caller's responsibility to manage the browser's
+   * lifecycle.
+   *
+   * If you want to close the browser using a scope simply add a finalizer:
+   *
+   * ```ts
+   * import { Effect } from "effect";
+   * import { Playwright } from "effect-playwright";
+   *
+   * const program = Effect.gen(function* () {
+   *   const browser = yield* Playwright.connectCDP(cdpUrl);
+   *   yield* Effect.addFinalizer(() => browser.close.pipe(Effect.ignore));
+   * });
+   *
+   * await Effect.runPromise(program);
+   * ```
+   *
+   * @param cdpUrl - The CDP URL to connect to.
+   * @param options - Optional options for connecting to the CDP URL.
+   * @since 0.1.0
+   */
+  connectCDP: (cdpUrl: string, options?: ConnectOverCDPOptions) => Effect.Effect<typeof PlaywrightBrowser.Service, PlaywrightError>;
+}
+declare const Playwright_base: Context.TagClass<Playwright, "effect-playwright/index/Playwright", PlaywrightService>;
+declare class Playwright extends Playwright_base {
+  /**
+   * @category layer
+   */
+  static readonly layer: Layer.Layer<Playwright, never, never>;
+}
+//#endregion
+export { NewPageOptions as a, PlaywrightPageService as c, PlaywrightError as d, NewContextOptions as i, PlaywrightLocator as l, PlaywrightService as n, PlaywrightBrowser as o, LaunchOptions$1 as r, PlaywrightPage as s, Playwright as t, PlaywrightLocatorService as u };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { a as NewPageOptions, c as PlaywrightPageService, i as NewContextOptions, l as PlaywrightLocator, n as PlaywrightService, o as PlaywrightBrowser, r as LaunchOptions, s as PlaywrightPage, t as Playwright, u as PlaywrightLocatorService } from "./index-aR0Fa_4Y.mjs";
+export { LaunchOptions, NewContextOptions, NewPageOptions, Playwright, PlaywrightBrowser, PlaywrightLocator, PlaywrightLocatorService, PlaywrightPage, PlaywrightPageService, PlaywrightService };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { i as PlaywrightLocator, n as PlaywrightBrowser, r as PlaywrightPage, t as Playwright } from "./src-DveiwW4g.mjs";
+
+export { Playwright, PlaywrightBrowser, PlaywrightLocator, PlaywrightPage };

package/dist/src-DveiwW4g.mjs

@@ -0,0 +1,167 @@
+import { Context, Data, Effect, Layer, Stream } from "effect";
+import { chromium, errors } from "playwright-core";
+
+//#region src/errors.ts
+var PlaywrightError = class extends Data.TaggedError("PlaywrightError") {};
+function wrapError(error) {
+	if (error instanceof errors.TimeoutError) return new PlaywrightError({
+		reason: "Timeout",
+		cause: error
+	});
+	else return new PlaywrightError({
+		reason: "Unknown",
+		cause: error
+	});
+}
+
+//#endregion
+//#region src/utils.ts
+/** @internal */
+const useHelper = (api) => (userFunction) => Effect.tryPromise(() => userFunction(api)).pipe(Effect.mapError(wrapError));
+
+//#endregion
+//#region src/locator.ts
+/**
+* A service that provides a `PlaywrightLocator` instance.
+*
+* @since 0.1.0
+* @category tag
+*/
+var PlaywrightLocator = class PlaywrightLocator extends Context.Tag("effect-playwright/PlaywrightLocator")() {
+	/**
+	* Creates a `PlaywrightLocator` from a Playwright `Locator` instance. This is mostly for internal use.
+	* But you could use this if you have used `use` or similar to wrap the locator.
+	*
+	* @example
+	* ```ts
+	* const playwrightNativeLocator = yield* page.use((p) => p.locator("button"));
+	* const locator = PlaywrightLocator.make(playwrightNativeLocator);
+	* ```
+	*
+	* @param locator - The Playwright `Locator` instance to wrap.
+	* @since 0.1.0
+	* @category constructor
+	*/
+	static make(locator) {
+		const use = useHelper(locator);
+		return PlaywrightLocator.of({
+			click: (options) => use((l) => l.click(options)),
+			fill: (value, options) => use((l) => l.fill(value, options)),
+			getAttribute: (name, options) => use((l) => l.getAttribute(name, options)),
+			innerText: (options) => use((l) => l.innerText(options)),
+			innerHTML: (options) => use((l) => l.innerHTML(options)),
+			inputValue: (options) => use((l) => l.inputValue(options)),
+			textContent: (options) => use((l) => l.textContent(options)),
+			count: use((l) => l.count()),
+			first: () => PlaywrightLocator.make(locator.first()),
+			last: () => PlaywrightLocator.make(locator.last()),
+			nth: (index) => PlaywrightLocator.make(locator.nth(index)),
+			evaluate: (pageFunction, arg, options) => use((l) => l.evaluate(pageFunction, arg, options)),
+			use
+		});
+	}
+};
+
+//#endregion
+//#region src/page.ts
+/**
+* @category tag
+*/
+var PlaywrightPage = class PlaywrightPage extends Context.Tag("effect-playwright/PlaywrightPage")() {
+	/**
+	* Creates a `PlaywrightPage` from a Playwright `Page` instance.
+	*
+	* @param page - The Playwright `Page` instance to wrap.
+	* @since 0.1.0
+	*/
+	static make(page) {
+		const use = useHelper(page);
+		return PlaywrightPage.of({
+			goto: (url, options) => use((p) => p.goto(url, options)),
+			waitForURL: (url, options) => use((p) => p.waitForURL(url, options)),
+			title: use((p) => p.title()),
+			evaluate: (f, arg) => use((p) => p.evaluate(f, arg)),
+			locator: (selector, options) => PlaywrightLocator.make(page.locator(selector, options)),
+			getByRole: (role, options) => PlaywrightLocator.make(page.getByRole(role, options)),
+			getByText: (text, options) => PlaywrightLocator.make(page.getByText(text, options)),
+			getByLabel: (label, options) => PlaywrightLocator.make(page.getByLabel(label, options)),
+			getByTestId: (testId) => PlaywrightLocator.make(page.getByTestId(testId)),
+			url: Effect.sync(() => page.url()),
+			reload: use((p) => p.reload()),
+			close: use((p) => p.close()),
+			click: (selector, options) => use((p) => p.click(selector, options)),
+			eventStream: (event) => Stream.asyncPush((emit) => Effect.acquireRelease(Effect.sync(() => page.on(event, emit.single)), () => Effect.sync(() => page.off(event, emit.single)))),
+			use
+		});
+	}
+};
+
+//#endregion
+//#region src/browser-context.ts
+var PlaywrightBrowserContext = class PlaywrightBrowserContext extends Context.Tag("cehs/backend/lib/playwright/PlaywrightBrowserContext")() {
+	static make(context) {
+		const use = useHelper(context);
+		return PlaywrightBrowserContext.of({
+			pages: Effect.sync(() => context.pages().map(PlaywrightPage.make)),
+			newPage: use((c) => c.newPage().then(PlaywrightPage.make)),
+			close: use((c) => c.close())
+		});
+	}
+};
+
+//#endregion
+//#region src/browser.ts
+/**
+* @category tag
+*/
+var PlaywrightBrowser = class PlaywrightBrowser extends Context.Tag("cehs/backend/lib/playwright/PlaywrightBrowser")() {
+	/**
+	* @category constructor
+	*/
+	static make(browser) {
+		const use = useHelper(browser);
+		return PlaywrightBrowser.of({
+			newPage: (options) => use((browser$1) => browser$1.newPage(options).then(PlaywrightPage.make)),
+			close: use((browser$1) => browser$1.close()),
+			contexts: Effect.sync(() => browser.contexts().map(PlaywrightBrowserContext.make)),
+			newContext: (options) => Effect.acquireRelease(use((browser$1) => browser$1.newContext(options).then(PlaywrightBrowserContext.make)), (context) => context.close.pipe(Effect.ignoreLogged)),
+			browserType: Effect.sync(() => browser.browserType()),
+			version: Effect.sync(() => browser.version()),
+			isConnected: Effect.sync(() => browser.isConnected()),
+			use
+		});
+	}
+};
+
+//#endregion
+//#region src/playwright.ts
+const launch = Effect.fn(function* (browserType, options) {
+	const rawBrowser = yield* Effect.tryPromise({
+		try: () => browserType.launch(options),
+		catch: wrapError
+	});
+	return PlaywrightBrowser.make(rawBrowser);
+});
+var Playwright = class Playwright extends Context.Tag("effect-playwright/index/Playwright")() {
+	/**
+	* @category layer
+	*/
+	static layer = Layer.succeed(Playwright, {
+		launch,
+		launchScoped: Effect.fn(function* (browserType, options) {
+			const browser = yield* launch(browserType, options);
+			yield* Effect.addFinalizer(() => browser.close.pipe(Effect.ignore));
+			return browser;
+		}),
+		connectCDP: Effect.fn(function* (cdpUrl, options) {
+			const browser = yield* Effect.tryPromise({
+				try: () => chromium.connectOverCDP(cdpUrl, options),
+				catch: wrapError
+			});
+			return PlaywrightBrowser.make(browser);
+		})
+	});
+};
+
+//#endregion
+export { PlaywrightLocator as i, PlaywrightBrowser as n, PlaywrightPage as r, Playwright as t };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "effect-playwright",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "An Effect-based Playwright library.",
+  "author": "Jobflow GmbH",
+  "license": "ISC",
+  "homepage": "https://github.com/Jobflow-io/effect-playwright",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jobflow-io/effect-playwright.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Jobflow-io/effect-playwright/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./experimental": "./dist/experimental/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "effect",
+    "effect-ts",
+    "playwright",
+    "browser",
+    "automation"
+  ],
+  "dependencies": {
+    "playwright-core": "^1.57.0"
+  },
+  "peerDependencies": {
+    "@effect/platform": "^0.93.3",
+    "effect": "^3.19.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@effect/language-service": "^0.64.1",
+    "@effect/platform": "^0.94.1",
+    "@effect/platform-node": "^0.104.0",
+    "@effect/vitest": "^0.27.0",
+    "effect": "^3.19.14",
+    "playwright": "^1.57.0",
+    "tsdown": "^0.19.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "types": "./dist/index.d.mts",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  }
+}