@opscotch/resource-testkit 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @opscotch/resource-testkit
+
+`@opscotch/resource-testkit` is the npm-distributed JavaScript unit test runtime for Opscotch resource files.
+
+It provides the same best-effort runtime shim used by the Docker-based Opscotch resource testkit, but packaged for local IDE use and direct Vitest/Jest-style test authoring.
+
+## Scope
+
+This package is intended for unit testing Opscotch JavaScript resources.
+
+It is not the production Opscotch agent runtime.
+
+Some features are fully implemented in-memory for test realism, such as:
+
+- `doc`
+- `JavascriptContext` and `JavascriptStateContext` core flow
+- byte-buffer handling
+- send/metric/log recording
+
+Some complex features remain stubbed or mock-first, such as:
+
+- parts of `crypto()`
+- parts of `files()`
+- parts of `queue()`
+
+## Install
+
+Install from npmjs:
+
+```bash
+npm install -D @opscotch/resource-testkit@0.1.0 vitest typescript @types/node
+```
+
+## Example
+
+```ts
+import { createJavascriptContext, runResource } from '@opscotch/resource-testkit';
+
+const context = createJavascriptContext({
+  body: '{"hello":"world"}',
+});
+
+await runResource({
+  resource: '/path/to/resource.js',
+  context,
+});
+```
+
+## Publishing
+
+This package is intended to be published to npmjs as a public scoped package.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createDocRuntime, type DocRuntime, } from './runtime/doc.js';
+export { createByteContext, type ByteBufferHandle, type ByteContextRuntime, type ByteReaderRuntime, } from './runtime/byte-context.js';
+export { createJavascriptContext, createAuthenticationJavascriptContext, createJavascriptStateContext, type ContextOptions, type JavascriptContextRuntime, type JavascriptStateRuntime, type StubPolicy, } from './runtime/context.js';
+export { runResource, type RunResourceOptions, type RunResourceResult, } from './runtime/run-resource.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createDocRuntime, } from './runtime/doc.js';
+export { createByteContext, } from './runtime/byte-context.js';
+export { createJavascriptContext, createAuthenticationJavascriptContext, createJavascriptStateContext, } from './runtime/context.js';
+export { runResource, } from './runtime/run-resource.js';

package/dist/runtime/byte-context.d.ts

@@ -0,0 +1,38 @@
+export type ByteBufferHandle = string & {
+    readonly __brand: 'ByteBufferHandle';
+};
+export interface ByteReaderRuntime {
+    read(length: number): ByteBufferHandle;
+    readAll(): ByteBufferHandle;
+    available(): number;
+}
+export interface ByteContextRuntime {
+    create(size: number): ByteBufferHandle;
+    createFromByteArray(bytes: number[] | Uint8Array): ByteBufferHandle;
+    createFromString(value: string): ByteBufferHandle;
+    copy(source: ByteBufferHandle): ByteBufferHandle;
+    slice(source: ByteBufferHandle, offset: number, length: number): ByteBufferHandle;
+    split(buffer: ByteBufferHandle, delimiter: ByteBufferHandle, includeDelimiter: number): ByteBufferHandle[];
+    resize(buffer: ByteBufferHandle, newSize: number): ByteBufferHandle;
+    getSize(buffer: ByteBufferHandle): number;
+    toString(buffer: ByteBufferHandle): string;
+    writeByte(buffer: ByteBufferHandle, offset: number, value: number): void;
+    readByte(buffer: ByteBufferHandle, offset: number): number;
+    writeBytes(toBuffer: ByteBufferHandle, offset: number, sourceBuffer: ByteBufferHandle, sourceOffset: number, length: number): void;
+    concat(buffers: ByteBufferHandle[]): ByteBufferHandle;
+    hexToBinary(hex: string): ByteBufferHandle;
+    binaryToHex(buffer: ByteBufferHandle): string;
+    base64ToBinary(base64: string): ByteBufferHandle;
+    binaryToBase64(buffer: ByteBufferHandle): string;
+    hash(buffer: ByteBufferHandle): number;
+    sha256(buffer: ByteBufferHandle): ByteBufferHandle;
+    gzip(buffer: ByteBufferHandle): ByteBufferHandle;
+    gunzip(buffer: ByteBufferHandle): ByteBufferHandle;
+    zip(buffer: ByteBufferHandle): ByteBufferHandle;
+    unzip(buffer: ByteBufferHandle): ByteBufferHandle;
+    reader(buffer: ByteBufferHandle): ByteReaderRuntime;
+    release(buffers: ByteBufferHandle[]): void;
+    inspect(buffer: ByteBufferHandle): Uint8Array;
+}
+export declare function createByteContext(): ByteContextRuntime;
+export declare function createRandomBufferHandle(byteContext: ByteContextRuntime, length: number): ByteBufferHandle;

package/dist/runtime/byte-context.js

@@ -0,0 +1,177 @@
+import { createHash, randomBytes as nodeRandomBytes } from 'node:crypto';
+import { deflateSync, gunzipSync, gzipSync, inflateSync } from 'node:zlib';
+export function createByteContext() {
+    let sequence = 0;
+    const buffers = new Map();
+    const nextHandle = () => `buf_${++sequence}`;
+    const put = (bytes) => {
+        const handle = nextHandle();
+        buffers.set(handle, bytes);
+        return handle;
+    };
+    const get = (handle) => {
+        const value = buffers.get(handle);
+        if (!value) {
+            throw new Error(`No buffer exists for key: ${handle}`);
+        }
+        return value;
+    };
+    const checkOffsets = (bytes, offset, length) => {
+        if (offset < 0 || offset > bytes.length || offset + length > bytes.length) {
+            throw new RangeError(`Invalid buffer offset (${offset}) and length (${length}) for buffer length (${bytes.length})`);
+        }
+    };
+    const toUint8Array = (value) => value instanceof Uint8Array ? new Uint8Array(value) : Uint8Array.from(value);
+    return {
+        create(size) {
+            return put(new Uint8Array(size));
+        },
+        createFromByteArray(bytes) {
+            return put(toUint8Array(bytes));
+        },
+        createFromString(value) {
+            return put(Buffer.from(value, 'utf8'));
+        },
+        copy(source) {
+            return put(new Uint8Array(get(source)));
+        },
+        slice(source, offset, length) {
+            const bytes = get(source);
+            checkOffsets(bytes, offset, length);
+            return put(bytes.slice(offset, offset + length));
+        },
+        split(buffer, delimiter, includeDelimiter) {
+            if (includeDelimiter < -1 || includeDelimiter > 1) {
+                throw new Error('includeDelimiter must be -1, 0, or 1');
+            }
+            const source = get(buffer);
+            const delim = get(delimiter);
+            if (delim.length === 0) {
+                return [put(source.slice())];
+            }
+            const matches = [];
+            for (let i = 0; i <= source.length - delim.length;) {
+                let matched = true;
+                for (let j = 0; j < delim.length; j += 1) {
+                    if (source[i + j] !== delim[j]) {
+                        matched = false;
+                        break;
+                    }
+                }
+                if (matched) {
+                    matches.push(i);
+                    i += delim.length;
+                }
+                else {
+                    i += 1;
+                }
+            }
+            const parts = [];
+            let start = 0;
+            for (const match of matches) {
+                const end = includeDelimiter === -1 ? match + delim.length : match;
+                parts.push(put(source.slice(start, end)));
+                start = includeDelimiter === 1 ? match : match + delim.length;
+            }
+            parts.push(put(source.slice(start)));
+            return parts;
+        },
+        resize(buffer, newSize) {
+            const bytes = get(buffer);
+            const resized = new Uint8Array(newSize);
+            resized.set(bytes.slice(0, newSize));
+            return put(resized);
+        },
+        getSize(buffer) {
+            return get(buffer).length;
+        },
+        toString(buffer) {
+            return Buffer.from(get(buffer)).toString('utf8');
+        },
+        writeByte(buffer, offset, value) {
+            const bytes = get(buffer);
+            checkOffsets(bytes, offset, 1);
+            bytes[offset] = value & 0xff;
+        },
+        readByte(buffer, offset) {
+            return get(buffer)[offset] ?? 0;
+        },
+        writeBytes(toBuffer, offset, sourceBuffer, sourceOffset, length) {
+            const target = get(toBuffer);
+            const source = get(sourceBuffer);
+            checkOffsets(target, offset, length);
+            checkOffsets(source, sourceOffset, length);
+            target.set(source.slice(sourceOffset, sourceOffset + length), offset);
+        },
+        concat(inputBuffers) {
+            const joined = Buffer.concat(inputBuffers.map((buffer) => Buffer.from(get(buffer))));
+            return put(new Uint8Array(joined));
+        },
+        hexToBinary(hex) {
+            return put(new Uint8Array(Buffer.from(hex, 'hex')));
+        },
+        binaryToHex(buffer) {
+            return Buffer.from(get(buffer)).toString('hex');
+        },
+        base64ToBinary(base64) {
+            return put(new Uint8Array(Buffer.from(base64, 'base64')));
+        },
+        binaryToBase64(buffer) {
+            return Buffer.from(get(buffer)).toString('base64');
+        },
+        hash(buffer) {
+            const digest = createHash('sha256').update(get(buffer)).digest();
+            return digest.readUInt32BE(0);
+        },
+        sha256(buffer) {
+            return put(new Uint8Array(createHash('sha256').update(get(buffer)).digest()));
+        },
+        gzip(buffer) {
+            return put(new Uint8Array(gzipSync(get(buffer))));
+        },
+        gunzip(buffer) {
+            return put(new Uint8Array(gunzipSync(get(buffer))));
+        },
+        zip(buffer) {
+            return put(new Uint8Array(deflateSync(get(buffer))));
+        },
+        unzip(buffer) {
+            return put(new Uint8Array(inflateSync(get(buffer))));
+        },
+        reader(buffer) {
+            const bytes = get(buffer);
+            let offset = 0;
+            return {
+                read(length) {
+                    const chunk = bytes.slice(offset, offset + length);
+                    offset += chunk.length;
+                    return put(chunk);
+                },
+                readAll() {
+                    const chunk = bytes.slice(offset);
+                    offset = bytes.length;
+                    return put(chunk);
+                },
+                available() {
+                    return bytes.length - offset;
+                },
+            };
+        },
+        release(inputBuffers) {
+            for (const handle of inputBuffers) {
+                const bytes = buffers.get(handle);
+                if (!bytes) {
+                    continue;
+                }
+                bytes.fill(0);
+                buffers.delete(handle);
+            }
+        },
+        inspect(buffer) {
+            return new Uint8Array(get(buffer));
+        },
+    };
+}
+export function createRandomBufferHandle(byteContext, length) {
+    return byteContext.createFromByteArray(nodeRandomBytes(length));
+}

package/dist/runtime/context.d.ts

@@ -0,0 +1,116 @@
+import { type ByteContextRuntime, type ByteReaderRuntime } from './byte-context.js';
+export type StubPolicy = 'warn' | 'throw';
+type RuntimeFn = (...args: any[]) => unknown;
+export interface JavascriptStateRuntime {
+    getMessageBodyAsString(): string | null;
+    getBody(): string | null;
+    getStepProperties(): Record<string, unknown>;
+    getProperty(key: string): unknown;
+    isErrored(): boolean;
+    getAllErrors(): string[];
+    hasUserErrors(): boolean;
+    hasSystemErrors(): boolean;
+    getUserErrors(): string[];
+    getSystemErrors(): string[];
+    getFirstError(errors: string[] | null | undefined): string | null;
+}
+export interface ContextOptions {
+    body?: string | null;
+    passedMessage?: string | null;
+    data?: Record<string, unknown> | null;
+    headers?: Record<string, string>;
+    properties?: Record<string, unknown>;
+    stepProperties?: Record<string, unknown>;
+    persistedItems?: Record<string, string>;
+    timestamp?: number;
+    byteContext?: ByteContextRuntime;
+    stubPolicy?: StubPolicy;
+    sendToStep?: (call: SendToStepCall) => Partial<StateSnapshot> | JavascriptStateRuntime | void;
+    sendToStepAndForget?: (call: SendToStepCall) => void;
+    crypto?: Record<string, RuntimeFn>;
+    files?: Record<string, RuntimeFn>;
+    queue?: Record<string, RuntimeFn>;
+    restrictedData?: Record<string, string>;
+    authenticationProperties?: Record<string, Record<string, string>>;
+}
+export interface JavascriptContextRuntime extends JavascriptStateRuntime {
+    __warnings: string[];
+    __metrics: MetricRecord[];
+    __logs: string[];
+    __sendToStepCalls: SendToStepCall[];
+    __sendToStepAndForgetCalls: SendToStepCall[];
+    __splitReturnItems: string[];
+    __ended: boolean;
+    __url?: {
+        hostRef: string;
+        path: string;
+    };
+    __method?: string | null;
+    addUserError(error: string): void;
+    addSystemError(error: string): void;
+    getPassedMessageAsString(): string | null;
+    setBody(body: unknown): void;
+    setMessage(body: unknown): void;
+    setStream(reader: ByteReaderRuntime | null): void;
+    setStreamFromString(value: string): void;
+    getStream(): ByteReaderRuntime | null;
+    setHttpMultipartType(textPartName: string, contentType: string, binaryPartName: string, binaryContentType: string, binaryFileName: string): void;
+    sendToStep(routeName: string, body?: string | null, headers?: Record<string, string>): JavascriptStateRuntime;
+    sendToStep(deploymentAccessId: string, stepName: string, body?: string | null, headers?: Record<string, string>): JavascriptStateRuntime;
+    sendToStepAndForget(stepName: string, body?: string | null, headers?: Record<string, string>): void;
+    sendToStepAndForget(deploymentAccessId: string, stepName: string, body?: string | null, headers?: Record<string, string>): void;
+    sendMetric(...args: unknown[]): void;
+    diagnosticLog(message: string): void;
+    getHeader(name: string): string | null;
+    setHeader(name: string, value: string): void;
+    removeHeader(name: string): void;
+    removeAllHeaders(): void;
+    setData(data: string): void;
+    getData(key?: string): string | null;
+    getTimestamp(): number;
+    getTimestampManager(): {
+        get(key: string): number;
+        set(key: string, value: number | string): void;
+        firstTimestamp(): number | null;
+        minutesAgo(timestamp: number | string): number;
+    };
+    setProperty(key: string, value: unknown): void;
+    getProperty(key: string): unknown;
+    setPersistedItem(key: string, value: string): void;
+    getPersistedItem(key: string): string | null;
+    queue(): Record<string, RuntimeFn>;
+    counter(name: string, add: number): number;
+    setCounter(name: string, value: number): void;
+    bytes(): ByteContextRuntime;
+    crypto(): Record<string, RuntimeFn>;
+    files(id?: string): Record<string, RuntimeFn>;
+    getStepProperties(): Record<string, unknown>;
+    addSplitReturnItem(item: string): void;
+    setHttpMethod(method: string): void;
+    setUrl(hostRef: string, path: string): void;
+    end(): void;
+    sleep(ms: number): Promise<void>;
+    delta(key: string, currentValue: number): number;
+    regexMatch(regex: string, input: string): string[] | null;
+    mergeJsonStrings(one: string | null, two: string | null): string;
+}
+export interface MetricRecord {
+    args: unknown[];
+}
+export interface SendToStepCall {
+    deploymentAccessId?: string;
+    stepName: string;
+    body: string | null;
+    headers?: Record<string, string>;
+}
+interface StateSnapshot {
+    body: string | null;
+    properties: Record<string, unknown>;
+    stepProperties: Record<string, unknown>;
+    userErrors: string[];
+    systemErrors: string[];
+}
+export declare function createJavascriptStateContext(snapshot?: Partial<StateSnapshot>): JavascriptStateRuntime;
+export declare function createJavascriptContext(options?: ContextOptions): JavascriptContextRuntime;
+export declare function createAuthenticationJavascriptContext(options?: ContextOptions): JavascriptContextRuntime;
+export {};

package/dist/runtime/context.js

@@ -0,0 +1,408 @@
+import { createHmac } from 'node:crypto';
+import { createByteContext, createRandomBufferHandle } from './byte-context.js';
+const RESTRICTED_AUTH_METHODS = new Set([
+    'setStream',
+    'setStreamFromString',
+    'getStream',
+    'setHttpMultipartType',
+    'diagnostic',
+    'sendMetric',
+    'files',
+    'agentControl',
+]);
+const noopObject = () => ({});
+export function createJavascriptStateContext(snapshot = {}) {
+    const state = {
+        body: snapshot.body ?? null,
+        properties: { ...(snapshot.properties ?? {}) },
+        stepProperties: { ...(snapshot.stepProperties ?? {}) },
+        userErrors: [...(snapshot.userErrors ?? [])],
+        systemErrors: [...(snapshot.systemErrors ?? [])],
+    };
+    return {
+        getMessageBodyAsString() {
+            return state.body;
+        },
+        getBody() {
+            return state.body;
+        },
+        getStepProperties() {
+            return state.stepProperties;
+        },
+        getProperty(key) {
+            return state.properties[key];
+        },
+        isErrored() {
+            return state.userErrors.length > 0 || state.systemErrors.length > 0;
+        },
+        getAllErrors() {
+            return [...state.userErrors, ...state.systemErrors];
+        },
+        hasUserErrors() {
+            return state.userErrors.length > 0;
+        },
+        hasSystemErrors() {
+            return state.systemErrors.length > 0;
+        },
+        getUserErrors() {
+            return [...state.userErrors];
+        },
+        getSystemErrors() {
+            return [...state.systemErrors];
+        },
+        getFirstError(errors) {
+            return errors?.[0] ?? null;
+        },
+    };
+}
+export function createJavascriptContext(options = {}) {
+    const warnings = [];
+    const metrics = [];
+    const logs = [];
+    const sendToStepCalls = [];
+    const sendToStepAndForgetCalls = [];
+    const byteContext = options.byteContext ?? createByteContext();
+    const stubPolicy = options.stubPolicy ?? 'warn';
+    const properties = { ...(options.properties ?? {}) };
+    const stepProperties = { ...(options.stepProperties ?? {}) };
+    const persistedItems = new Map(Object.entries(options.persistedItems ?? {}));
+    const headers = new Map(Object.entries(options.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+    const counters = new Map();
+    const timestamps = new Map();
+    const splitReturnItems = [];
+    const data = { ...(options.data ?? {}) };
+    let body = options.body ?? null;
+    let passedMessage = options.passedMessage ?? null;
+    let currentStream = null;
+    let ended = false;
+    let url;
+    let method = null;
+    const userErrors = [];
+    const systemErrors = [];
+    let multipart;
+    const warnOrThrow = (name) => {
+        const message = `Stub invoked without explicit mock: ${name}`;
+        if (stubPolicy === 'throw') {
+            throw new Error(message);
+        }
+        warnings.push(message);
+    };
+    const createGenericStub = (namespace) => new Proxy(noopObject(), {
+        get(target, prop) {
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            if (prop in target) {
+                return target[prop];
+            }
+            return (...args) => {
+                warnOrThrow(`${namespace}.${prop}`);
+                if (namespace === 'crypto' && prop === 'randomBytes') {
+                    return createRandomBufferHandle(byteContext, Number(args[0] ?? 0));
+                }
+                if (namespace === 'crypto' && prop === 'hash') {
+                    const input = args[0];
+                    return byteContext.sha256(input);
+                }
+                if (namespace === 'crypto' && prop === 'hmacSha256') {
+                    const key = args[0];
+                    const bytes = args[1];
+                    const digest = createHmac('sha256', byteContext.inspect(key)).update(byteContext.inspect(bytes)).digest();
+                    return byteContext.createFromByteArray(digest);
+                }
+                if (namespace === 'crypto' && prop === 'verifySignature') {
+                    return false;
+                }
+                if (namespace === 'crypto' && prop === 'registerKey') {
+                    return 'stub-key-id';
+                }
+                if (namespace === 'crypto' && prop === 'generateKeyPair') {
+                    return [byteContext.create(0), byteContext.create(0)];
+                }
+                if (namespace === 'crypto' && prop === 'passwordHash') {
+                    return [byteContext.create(0), byteContext.create(0)];
+                }
+                if (namespace === 'files') {
+                    return undefined;
+                }
+                if (namespace === 'queue') {
+                    return undefined;
+                }
+                return byteContext.create(0);
+            };
+        },
+    });
+    const cryptoContext = Object.assign(createGenericStub('crypto'), options.crypto ?? {});
+    const filesContext = Object.assign(createGenericStub('files'), options.files ?? {});
+    const queueContext = Object.assign(createGenericStub('queue'), options.queue ?? {});
+    const runtime = {
+        __warnings: warnings,
+        __metrics: metrics,
+        __logs: logs,
+        __sendToStepCalls: sendToStepCalls,
+        __sendToStepAndForgetCalls: sendToStepAndForgetCalls,
+        __splitReturnItems: splitReturnItems,
+        __ended: ended,
+        getPassedMessageAsString() {
+            return passedMessage;
+        },
+        getMessageBodyAsString() {
+            return body;
+        },
+        getBody() {
+            return body ?? passedMessage;
+        },
+        setBody(value) {
+            body = value == null ? null : String(value);
+        },
+        setMessage(value) {
+            body = value == null ? null : String(value);
+        },
+        setStream(reader) {
+            currentStream = reader;
+            if (reader != null) {
+                body = null;
+            }
+        },
+        setStreamFromString(value) {
+            const handle = byteContext.createFromString(value);
+            currentStream = byteContext.reader(handle);
+            body = null;
+        },
+        getStream() {
+            return currentStream;
+        },
+        setHttpMultipartType(textPartName, contentType, binaryPartName, binaryContentType, binaryFileName) {
+            multipart = { textPartName, contentType, binaryPartName, binaryContentType, binaryFileName };
+            void multipart;
+        },
+        sendToStep: ((...args) => {
+            const call = normalizeSendCall(args);
+            sendToStepCalls.push(call);
+            const returned = options.sendToStep?.(call);
+            if (!returned) {
+                return createJavascriptStateContext({ body: call.body });
+            }
+            if (isJavascriptStateRuntime(returned)) {
+                return returned;
+            }
+            return createJavascriptStateContext(returned);
+        }),
+        sendToStepAndForget: ((...args) => {
+            const call = normalizeSendCall(args);
+            sendToStepAndForgetCalls.push(call);
+            options.sendToStepAndForget?.(call);
+        }),
+        sendMetric(...args) {
+            metrics.push({ args });
+        },
+        diagnosticLog(message) {
+            logs.push(message);
+        },
+        addUserError(error) {
+            userErrors.push(error);
+        },
+        addSystemError(error) {
+            systemErrors.push(error);
+        },
+        isErrored() {
+            return userErrors.length > 0 || systemErrors.length > 0;
+        },
+        getAllErrors() {
+            return [...userErrors, ...systemErrors];
+        },
+        hasUserErrors() {
+            return userErrors.length > 0;
+        },
+        hasSystemErrors() {
+            return systemErrors.length > 0;
+        },
+        getUserErrors() {
+            return [...userErrors];
+        },
+        getSystemErrors() {
+            return [...systemErrors];
+        },
+        getFirstError(errors) {
+            return errors?.[0] ?? null;
+        },
+        getHeader(name) {
+            return headers.get(name.toLowerCase()) ?? null;
+        },
+        setHeader(name, value) {
+            headers.set(name.toLowerCase(), value);
+        },
+        removeHeader(name) {
+            headers.delete(name.toLowerCase());
+        },
+        removeAllHeaders() {
+            headers.clear();
+        },
+        setData(rawData) {
+            Object.keys(data).forEach((key) => delete data[key]);
+            const parsed = JSON.parse(rawData);
+            Object.assign(data, parsed);
+        },
+        getData(key) {
+            if (key == null) {
+                return JSON.stringify(data);
+            }
+            const value = data[key];
+            if (value == null) {
+                return null;
+            }
+            return typeof value === 'string' ? value : JSON.stringify(value);
+        },
+        getTimestamp() {
+            return options.timestamp ?? Date.now();
+        },
+        getTimestampManager() {
+            return {
+                get(key) {
+                    return timestamps.get(key) ?? 0;
+                },
+                set(key, value) {
+                    timestamps.set(key, Number(value));
+                },
+                firstTimestamp() {
+                    const values = Array.from(timestamps.values()).filter((value) => Number.isFinite(value));
+                    if (values.length === 0) {
+                        return null;
+                    }
+                    return Math.min(...values);
+                },
+                minutesAgo(timestamp) {
+                    const then = Number(timestamp);
+                    return Math.floor((runtime.getTimestamp() - then) / 60000);
+                },
+            };
+        },
+        setProperty(key, value) {
+            properties[key] = value;
+        },
+        getProperty(key) {
+            return properties[key];
+        },
+        setPersistedItem(key, value) {
+            persistedItems.set(key, value);
+        },
+        getPersistedItem(key) {
+            return persistedItems.get(key) ?? null;
+        },
+        queue() {
+            return queueContext;
+        },
+        counter(name, add) {
+            const next = (counters.get(name) ?? 0) + add;
+            counters.set(name, next);
+            return next;
+        },
+        setCounter(name, value) {
+            counters.set(name, value);
+        },
+        bytes() {
+            return byteContext;
+        },
+        crypto() {
+            return cryptoContext;
+        },
+        files() {
+            return filesContext;
+        },
+        getStepProperties() {
+            return stepProperties;
+        },
+        addSplitReturnItem(item) {
+            splitReturnItems.push(item);
+            void splitReturnItems;
+        },
+        setHttpMethod(nextMethod) {
+            method = nextMethod.toUpperCase();
+            runtime.__method = method;
+        },
+        setUrl(hostRef, path) {
+            url = { hostRef, path };
+            runtime.__url = url;
+        },
+        end() {
+            ended = true;
+            runtime.__ended = true;
+        },
+        async sleep(ms) {
+            if (ms <= 0) {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, ms));
+        },
+        delta(key, currentValue) {
+            const lookupKey = `DELTA-${key}`;
+            const previous = Number(persistedItems.get(lookupKey) ?? '0');
+            persistedItems.set(lookupKey, String(currentValue));
+            return currentValue - previous;
+        },
+        regexMatch(regex, input) {
+            const match = new RegExp(regex).exec(input);
+            return match ? Array.from(match) : null;
+        },
+        mergeJsonStrings(one, two) {
+            if (!one && !two) {
+                return '{}';
+            }
+            if (!one) {
+                return two ?? '{}';
+            }
+            if (!two) {
+                return one;
+            }
+            return JSON.stringify(deepMerge(JSON.parse(one), JSON.parse(two)));
+        },
+    };
+    return runtime;
+}
+export function createAuthenticationJavascriptContext(options = {}) {
+    const runtime = createJavascriptContext(options);
+    const restrictedData = new Map(Object.entries(options.restrictedData ?? {}));
+    const authProperties = new Map(Object.entries(options.authenticationProperties ?? {}).map(([step, values]) => [step, new Map(Object.entries(values))]));
+    const authRuntime = runtime;
+    authRuntime.getRestrictedDataFromHost = (host) => restrictedData.get(host) ?? null;
+    authRuntime.getAuthenticationPropertiesFromStep = (stepId, key) => authProperties.get(stepId)?.get(key) ?? null;
+    authRuntime.setAuthenticationPropertiesOnStep = (stepName, _expiresInMs, key, value) => {
+        if (!authProperties.has(stepName)) {
+            authProperties.set(stepName, new Map());
+        }
+        authProperties.get(stepName).set(key, value);
+    };
+    for (const method of RESTRICTED_AUTH_METHODS) {
+        authRuntime[method] = (() => {
+            throw new Error(`Operation not supported in authentication context: ${method}`);
+        });
+    }
+    return authRuntime;
+}
+function normalizeSendCall(args) {
+    if (args.length >= 3 && typeof args[2] !== 'object') {
+        const [deploymentAccessId, stepName, body, headers] = args;
+        return { deploymentAccessId, stepName, body: body ?? null, headers };
+    }
+    const [stepName, body, headers] = args;
+    return { stepName, body: body ?? null, headers };
+}
+function isJavascriptStateRuntime(value) {
+    return typeof value === 'object' && value != null && typeof value.getBody === 'function';
+}
+function deepMerge(left, right) {
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return right;
+    }
+    if (!isObject(left) || !isObject(right)) {
+        return right;
+    }
+    const merged = { ...left };
+    for (const [key, value] of Object.entries(right)) {
+        merged[key] = key in merged ? deepMerge(merged[key], value) : value;
+    }
+    return merged;
+}
+function isObject(value) {
+    return typeof value === 'object' && value != null && !Array.isArray(value);
+}

package/dist/runtime/doc.d.ts

@@ -0,0 +1,16 @@
+export type DocRunFunction = () => unknown | Promise<unknown>;
+export interface DocRuntime {
+    inSchemaValue?: unknown;
+    outSchemaValue?: unknown;
+    dataSchemaValue?: unknown;
+    descriptionValue?: string;
+    runFunction?: DocRunFunction;
+    userErrors: boolean;
+    inSchema(schema: unknown): DocRuntime;
+    outSchema(schema: unknown): DocRuntime;
+    dataSchema(schema: unknown): DocRuntime;
+    run(run: unknown): DocRuntime;
+    description(description: string): DocRuntime;
+    asUserErrors(): DocRuntime;
+}
+export declare function createDocRuntime(): DocRuntime;

package/dist/runtime/doc.js

@@ -0,0 +1,40 @@
+export function createDocRuntime() {
+    const runtime = {
+        userErrors: false,
+        inSchemaValue: undefined,
+        outSchemaValue: undefined,
+        dataSchemaValue: undefined,
+        descriptionValue: undefined,
+        runFunction: undefined,
+        inSchema(schema) {
+            runtime.inSchemaValue = schema;
+            return runtime;
+        },
+        outSchema(schema) {
+            runtime.outSchemaValue = schema;
+            return runtime;
+        },
+        dataSchema(schema) {
+            runtime.dataSchemaValue = schema;
+            return runtime;
+        },
+        run(run) {
+            if (typeof run === 'function') {
+                runtime.runFunction = run;
+            }
+            else {
+                throw new TypeError('doc.run(...) expects a function');
+            }
+            return runtime;
+        },
+        description(description) {
+            runtime.descriptionValue = description;
+            return runtime;
+        },
+        asUserErrors() {
+            runtime.userErrors = true;
+            return runtime;
+        },
+    };
+    return runtime;
+}

package/dist/runtime/run-resource.d.ts

@@ -0,0 +1,15 @@
+import { type DocRuntime } from './doc.js';
+import { type ContextOptions, type JavascriptContextRuntime } from './context.js';
+export interface RunResourceOptions {
+    resource: string;
+    context?: JavascriptContextRuntime;
+    contextOptions?: ContextOptions;
+    doc?: DocRuntime;
+    execute?: 'auto' | 'registration' | 'run';
+}
+export interface RunResourceResult {
+    context: JavascriptContextRuntime;
+    doc: DocRuntime;
+    returnValue: unknown;
+}
+export declare function runResource(options: RunResourceOptions): Promise<RunResourceResult>;

package/dist/runtime/run-resource.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs/promises';
+import vm from 'node:vm';
+import { createDocRuntime } from './doc.js';
+import { createJavascriptContext, } from './context.js';
+export async function runResource(options) {
+    const source = await fs.readFile(options.resource, 'utf8');
+    const context = options.context ?? createJavascriptContext(options.contextOptions);
+    const doc = options.doc ?? createDocRuntime();
+    const sandbox = {
+        context,
+        doc,
+        console,
+        JSON,
+        Buffer,
+        setTimeout,
+        clearTimeout,
+    };
+    const vmContext = vm.createContext(sandbox);
+    const script = new vm.Script(source, {
+        filename: options.resource,
+    });
+    let returnValue = script.runInContext(vmContext);
+    const execute = options.execute ?? 'auto';
+    const shouldRun = execute === 'run' || (execute === 'auto' && typeof doc.runFunction === 'function');
+    if (shouldRun && doc.runFunction) {
+        returnValue = await doc.runFunction();
+    }
+    return {
+        context,
+        doc,
+        returnValue,
+    };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@opscotch/resource-testkit",
+  "version": "0.1.0",
+  "description": "Unit test runtime shim for Opscotch JavaScript resources.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opscotch/opscotch.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "sync:source": "node ../../shared/opscotch-resource-testkit-source/sync-to-consumer.mjs ./src",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  }
+}