Skip to main content

Class: Browser

Defined in: packages/testing/src/index.ts:47

Testing-optimized Browser with automatic SELF.fetch injection.

This is a convenience wrapper around Browser from @lumenize/utils that automatically uses SELF.fetch from the Cloudflare Workers test environment when no fetch function is provided.

Environment Requirement: This class can only be instantiated within Cloudflare Workers test environment (vitest with @cloudflare/vitest-pool-workers). It lazily imports from cloudflare:test which is only available in that environment.

Example​

import { Browser } from '@lumenize/testing';

const browser = new Browser(); // Automatically uses SELF.fetch
await browser.fetch('http://localhost/api');

// Can still pass custom fetch if needed
const customBrowser = new Browser(myCustomFetch);

// With metrics tracking
const metrics: Metrics = {};
const browser = new Browser(undefined, { metrics });

Extends​

  • Browser

Constructors​

Constructor​

new Browser(fetchFn?, options?): Browser

Defined in: packages/testing/src/index.ts:48

Parameters​

fetchFn?​

{(input, init?): Promise<Response>; (input, init?): Promise<Response>; (input, init?): Promise<Response>; }

options?​

BrowserOptions

Returns​

Browser

Overrides​

BrowserBase.constructor

Accessors​

fetch​

Get Signature​

get fetch(): {(input, init?): Promise<Response>; (input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Defined in: packages/utils/src/browser.ts:128

Cookie-aware fetch function

Automatically includes cookies from this browser instance in requests and stores cookies from responses.

Example​
const browser = new Browser();

// First request sets session cookie
await browser.fetch('https://api.example.com/login?token=xyz');

// Subsequent requests include the cookie
const response = await browser.fetch('https://api.example.com/data');
Returns​

(input, init?): Promise<Response>

MDN Reference

Parameters​
input​

RequestInfo | URL

init?​

RequestInit<CfProperties<unknown>>

Returns​

Promise<Response>

(input, init?): Promise<Response>

MDN Reference

Parameters​
input​

RequestInfo | URL

init?​

RequestInit<RequestInitCfProperties>

Returns​

Promise<Response>

(input, init?): Promise<Response>

MDN Reference

Parameters​
input​

string | Request<unknown, CfProperties<unknown>> | URL

init?​

RequestInit<CfProperties<unknown>>

Returns​

Promise<Response>

Inherited from​

BrowserBase.fetch

WebSocket​

Get Signature​

get WebSocket(): (url, protocols?) => WebSocket

Defined in: packages/utils/src/browser.ts:189

Cookie-aware WebSocket constructor

Automatically includes cookies from this browser instance in the WebSocket upgrade request.

Example​
const browser = new Browser();
const ws = new browser.WebSocket('wss://api.example.com/stream');
ws.onopen = () => console.log('Connected!');
Returns​

new WebSocket(url, protocols?): WebSocket

Parameters​
url​

string | URL

protocols?​

string | string[]

Returns​

WebSocket

Inherited from​

BrowserBase.WebSocket

Methods​

context()​

context(origin, options?): object

Defined in: packages/utils/src/browser.ts:235

Create a context with Origin header for browser-like CORS behavior

Returns an object with fetch and WebSocket that both:

  • Include cookies from this browser
  • Include the specified Origin header
  • Include any custom headers

The fetch function returned by context() validates CORS headers and will throw a TypeError (like a real browser) if the server doesn't properly allow the origin.

Parameters​

origin​

string

The origin to use (e.g., 'https://example.com')

options?​

Optional headers and WebSocket configuration

headers?​

Record<string, string>

maxQueueBytes?​

number

Returns​

Object with fetch function and WebSocket constructor

fetch()​

fetch: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Call Signature​

(input, init?): Promise<Response>

MDN Reference

Parameters​
input​

RequestInfo | URL

init?​

RequestInit<CfProperties<unknown>>

Returns​

Promise<Response>

Call Signature​

(input, init?): Promise<Response>

MDN Reference

Parameters​
input​

RequestInfo | URL

init?​

RequestInit<RequestInitCfProperties>

Returns​

Promise<Response>

Call Signature​

(input, init?): Promise<Response>

MDN Reference

Parameters​
input​

string | Request<unknown, CfProperties<unknown>> | URL

init?​

RequestInit<CfProperties<unknown>>

Returns​

Promise<Response>

lastPreflight​

lastPreflight: null | PreflightInfo

WebSocket()​

WebSocket: (url, protocols?) => WebSocket

Parameters​
url​

string | URL

protocols?​

string | string[]

Returns​

WebSocket

Example​

const browser = new Browser();

// Simple usage - validates CORS on cross-origin requests
const page = browser.context('https://example.com');
await page.fetch('https://api.example.com/data'); // Validates CORS

// Same-origin request - no CORS validation needed
await page.fetch('https://example.com/data'); // No validation

// With custom headers
const page2 = browser.context('https://example.com', {
  headers: { 'X-Custom': 'value' },
  maxQueueBytes: 1024 * 1024
});
const ws = new page2.WebSocket('wss://api.example.com/ws');

// CORS error example - will throw TypeError
try {
  await browser.context('https://app.com').fetch('https://api.com/data');
  // Throws if api.com doesn't send proper CORS headers
} catch (err) {
  console.error('CORS error:', err); // TypeError: Failed to fetch
}

Inherited from​

BrowserBase.context

getAllCookies()​

getAllCookies(): object[]

Defined in: packages/utils/src/browser.ts:434

Get all cookies as an array of cookie objects

Returns​

object[]

Array of cookie objects with name, value, and metadata

Inherited from​

BrowserBase.getAllCookies

getAllCookiesAsObject()​

getAllCookiesAsObject(): Record<string, string>

Defined in: packages/utils/src/browser.ts:461

Get all cookies as a simple name-value object

Returns​

Record<string, string>

Object with cookie names as keys and values as values

Inherited from​

BrowserBase.getAllCookiesAsObject

getCookie()​

getCookie(name, domain?): undefined | string

Defined in: packages/utils/src/browser.ts:416

Get a specific cookie by name

Parameters​

name​

string

Cookie name

domain?​

string

Optional domain filter

Returns​

undefined | string

Cookie value or undefined if not found

Inherited from​

BrowserBase.getCookie

getCookiesForRequest()​

getCookiesForRequest(requestUrl): null | string

Defined in: packages/utils/src/browser.ts:340

Get cookies that should be included in a request

Automatically cleans up expired cookies.

Parameters​

requestUrl​

string

The URL being requested

Returns​

null | string

Cookie header value or null if no cookies match

Inherited from​

BrowserBase.getCookiesForRequest

removeCookie()​

removeCookie(name, domain?, path?): void

Defined in: packages/utils/src/browser.ts:481

Remove a cookie

Parameters​

name​

string

Cookie name

domain?​

string

Optional domain filter

path?​

string

Optional path filter

Returns​

void

Inherited from​

BrowserBase.removeCookie

setCookie()​

setCookie(name, value, options): void

Defined in: packages/utils/src/browser.ts:382

Set a cookie manually

Parameters​

name​

string

Cookie name

value​

string

Cookie value

options​

Omit<Cookie, "name" | "value"> = {}

Optional cookie attributes (domain, path, expires, etc.)

Returns​

void

Example​

browser.setCookie('auth_token', 'abc123', {
  domain: 'api.example.com',
  path: '/',
  expires: new Date(Date.now() + 3600000) // 1 hour
});

Inherited from​

BrowserBase.setCookie