RammerheadSession class reference

RammerheadSession extends testcafe-hammerhead’s Session class with cookie and localStorage persistence, URL-shuffling dictionaries, and serialization support. Each user that navigates through the proxy gets exactly one session, identified by a random ID. Sessions are normally created and retrieved through a session store — you rarely instantiate RammerheadSession directly.

The recommended way to create sessions is through a session store’s add(id) method after calling store.attachToProxy(proxy). Direct construction is only needed when deserializing a previously serialized session or in advanced testing scenarios.

Constructor

const session = new RammerheadSession(options);

string

default:"generateId()"

Unique session identifier. Defaults to a randomly generated alphanumeric string. Pass an explicit value when reconstructing a session from storage.

dontConnectToData

boolean

default:"false"

When true, the constructor skips the call to connectHammerheadToData(). Use this when you need to set session.data from a deserialized source before connecting hammerhead’s internal state to it. DeserializeSession uses this flag.

disableShuffling

boolean

default:"false"

When true, session.shuffleDict is set to null and URL shuffling is not applied for this session. Shuffling is enabled by default.

prependScripts

string[]

default:"[]"

Array of script URLs to inject into every proxied page before rammerhead.js. Useful for injecting custom initialization scripts.

Properties

data

object

Plain object that acts as the backing store for all session state (cookies, localStorage, createdAt, lastUsed, shuffleDict, and injectable). The connectHammerheadToData method wires hammerhead’s internal properties to read and write through this object, so data always reflects the current session state and is safe to serialize.

createdAt

number

Unix timestamp (milliseconds) when the session was created. Set once during construction and stored in data.createdAt.

lastUsed

number

Unix timestamp (milliseconds) of the last time the session was accessed. Updated by calling updateLastUsed(). Session stores use this value to evict stale sessions.

externalProxySettings

object | null

Upstream proxy configuration used by hammerhead when making outbound requests. When set, all requests from this session are forwarded through the specified upstream proxy.

Show properties

host

string

required

Proxy host including port, e.g. "proxy.example.com:3128".

hostname

string

required

Proxy hostname without port.

port

string

Proxy port as a string.

bypassRules

string[]

List of hostname patterns to bypass the proxy.

proxyAuth

string

Proxy authentication credentials in user:password format.

authHeader

string

Raw Proxy-Authorization header value.

overrideExternalProxySettings

object | null

When non-null, this value takes precedence over externalProxySettings for outbound requests. Useful for server-side proxy enforcement that cannot be overridden by client-supplied settings.

shuffleDict

object | null

The URL-shuffling character map dictionary for this session. Generated once by StrShuffler.generateDictionary() during construction. null when shuffling is disabled (disableShuffling: true). Clients fetch this dictionary from /api/shuffleDict?id=<sessionId> to decode proxied URLs.

Methods

connectHammerheadToData

session.connectHammerheadToData(dontCookie?)

Wires hammerhead’s internal session properties (createdAt, lastUsed, injectable, externalProxySettings, shuffleDict, and optionally cookies) to read from and write to session.data. Call this after manually setting session.data when deserializing.

When true, the cookie jar is not connected to data. Pass true when using serializeSession/DeserializeSession because those methods handle cookie serialization separately.

updateLastUsed

session.updateLastUsed()

Sets session.lastUsed to the current time (Date.now()). Session stores call this automatically on get(). Call it manually after any operation that counts as session activity.

serializeSession

const json = session.serializeSession()

Returns a JSON string containing the full session state: data and the serialized cookie jar. Use this to save a session to disk or transfer it between processes.

returns

string

A JSON string with shape { data: object, serializedCookieJar: object }.

DeserializeSession (static)

const session = RammerheadSession.DeserializeSession(id, serializedSession)

Reconstructs a RammerheadSession from a JSON string previously produced by serializeSession().

string

required

Session ID to assign to the restored session.

serializedSession

string

required

JSON string as returned by serializeSession().

returns

RammerheadSession

A fully initialized session with data and cookies restored.

Throws Error if serializedSession is missing data or serializedCookieJar fields, or if the JSON is malformed.

setExternalProxySettings

session.setExternalProxySettings(proxy)

Convenience method (used internally by the session management routes) to configure an upstream proxy for this session. Setting to null clears the upstream proxy.

proxy

object | null

required

An upstream proxy configuration object or null to remove it. Uses the same shape as externalProxySettings.

Example: creating and deserializing sessions

Via store (recommended)
Direct construction

const { RammerheadProxy, RammerheadSessionMemoryStore } = require('rammerhead');
const { randomUUID } = require('crypto');

const proxy = new RammerheadProxy({ port: 8080 });
const store = new RammerheadSessionMemoryStore();
store.attachToProxy(proxy);

// Create a new session
const id = randomUUID();
const session = store.add(id);

// Retrieve it later
const sameSession = store.get(id);

const { RammerheadSession } = require('rammerhead');

// Create with a specific ID and no shuffling
const session = new RammerheadSession({
  id: 'my-fixed-id',
  disableShuffling: true
});

// Serialize to a string for storage
const serialized = session.serializeSession();

// Later, restore the session
const restored = RammerheadSession.DeserializeSession('my-fixed-id', serialized);

Classes

Utilities

HTTP Endpoints

RammerheadSession class reference

Constructor

Properties

Methods

connectHammerheadToData

updateLastUsed

serializeSession

DeserializeSession (static)

setExternalProxySettings

Example: creating and deserializing sessions

Build docs developers (and LLMs) love

Classes

Utilities

HTTP Endpoints

Documentation Index

​Constructor

​Properties

​Methods

​connectHammerheadToData

​updateLastUsed

​serializeSession

​DeserializeSession (static)

​setExternalProxySettings

​Example: creating and deserializing sessions

Build docs developers (and LLMs) love

Constructor

Properties

Methods

connectHammerheadToData

updateLastUsed

serializeSession

DeserializeSession (static)

setExternalProxySettings

Example: creating and deserializing sessions