@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:

npm install -D @opscotch/[email protected] vitest typescript @types/node

Example

import path from 'node:path';
import { createJavascriptContext, createResourceSuite } from '@opscotch/resource-testkit';
import { describe, expect, it } from 'vitest';

const suite = createResourceSuite({
  baseDir: path.resolve(import.meta.dirname, '../resources'),
  resources: [{ id: 'sample-resource', resource: './sample-resource.js' }],
});

describe('sample-resource', () => {
  it('updates the payload body', async () => {
    const context = createJavascriptContext({
      body: JSON.stringify({
        operation: 'normalize',
        labels: ['A', 'b'],
      }),
    });

    await suite.run('sample-resource', { context });

    expect(JSON.parse(context.getBody() || '{}')).toEqual({
      status: 'ok',
      labels: ['a', 'b'],
    });
  });
});

Resource Suite (preferred for larger test sets)

Use a suite to register logical ids once, then run resources by id.

import path from 'node:path';
import { createJavascriptContext, createResourceSuite } from '@opscotch/resource-testkit';

const suite = createResourceSuite({
  baseDir: path.resolve(import.meta.dirname, '../resources'),
  resources: [
    { id: 'log-fetch-url-generator', resource: './log-fetch-url-generator.js' },
    { id: 'log-fetch-payload-generator', resource: './log-fetch-payload-generator.js' },
  ],
});

const context = createJavascriptContext({
  data: { openclawGatewayHostId: 'openclaw-local-gateway' },
});

await suite.run('log-fetch-url-generator', { context });

Publishing

This package is intended to be published to npmjs as a public scoped package.

License

This package is free to use, but use is conditioned on agreement to the Opscotch legal terms:

• https://www.opscotch.co/legal

The packaged license notice is included in LICENSE.txt.