Testing and resets

The SDK keeps global in-memory state (registry, validators, policy hooks, sessions, and more). In Vitest or Jest, call a reset in beforeEach / afterEach so one test does not leak into the next.

Import from the package root:


import {
  resetInspectorState,
  resetParamsJsonSchemaValidators,
  resetReturnJsonSchemaValidators,
  resetRpcSerializationConfig,
  resetInvokePolicy,
  resetInvokeTimeoutMs,
  resetSessionStore,
  clearHttpBridgeRegistry,
} from '@gloocan/cat-inspector'

`resetInspectorState()` — default for integration tests

One call clears everything the SDK shares between invokes: registry, instances, JSON Schema caches, HTTP bridge specs, policy hooks, serialization config, invoke timeout, session store, WebSocket client map, broadcast sink, and capture buffers.

Where to put it: top of the file or beforeEach in any suite that registers @Cat / cat() entries, calls executeRPC, bootstrap(), or starts a transport.


import { beforeEach, describe, it, expect } from 'vitest'
import { cat, executeRPC, resetInspectorState } from '@gloocan/cat-inspector'
 
beforeEach(() => {
  resetInspectorState()
})
 
describe('my service RPC', () => {
  it('invokes a registered handler', async () => {
    const fn = cat((n: number) => n + 1, { name: 'addOne' })
    const res = await executeRPC('addOne', [2])
    expect(res.status).toBe('ok')
  })
})

Use this when tests touch more than one subsystem (registration + RPC, or bootstrap + policy). The SDK’s own tests (rpc.test.ts, bootstrap.test.ts, transport tests) follow this pattern.

Granular resets — when you only touched one subsystem

Prefer a narrow reset when your suite only configures that piece of global state. That keeps unrelated globals intact if your test file depends on them (uncommon, but useful for pure unit tests).

`resetParamsJsonSchemaValidators`

Clears the AJV cache for parameter schemas only. Use in tests that call registerParamsJsonSchema / validateArgsAgainstParamsJsonSchema and re-register the same fnKey with different schema objects.


import { beforeEach, it, expect } from 'vitest'
import {
  Registry,
  registerParamsJsonSchema,
  resetParamsJsonSchemaValidators,
  validateArgsAgainstParamsJsonSchema,
} from '@gloocan/cat-inspector'
 
beforeEach(() => {
  resetParamsJsonSchemaValidators()
  Registry.clear() // registry entries are separate — clear or use resetInspectorState if you register fnKeys
})
 
it('validates args against an updated schema', () => {
  Registry.set('Demo.f', { /* minimal RegistryEntry */ params: [], /* … */ })
  registerParamsJsonSchema('Demo.f', { type: 'array', items: [{ type: 'number' }] })
  expect(validateArgsAgainstParamsJsonSchema('Demo.f', [1])).toBeNull()
})

`resetReturnJsonSchemaValidators`

Same idea for return JSON Schema validators (registerReturnJsonSchema).


import { beforeEach } from 'vitest'
import { resetReturnJsonSchemaValidators } from '@gloocan/cat-inspector'
 
beforeEach(() => {
  resetReturnJsonSchemaValidators()
})

`resetRpcSerializationConfig`

Clears setRpcSerializationConfig (enabled flag, maxUtf8Bytes, etc.). Use when testing serializeRpcResult in isolation without wiping the registry.


import { beforeEach, it, expect } from 'vitest'
import {
  resetRpcSerializationConfig,
  serializeRpcResult,
  setRpcSerializationConfig,
} from '@gloocan/cat-inspector'
 
beforeEach(() => {
  resetRpcSerializationConfig()
})
 
it('enforces maxUtf8Bytes when configured', () => {
  setRpcSerializationConfig({ enabled: true, maxUtf8Bytes: 10 })
  expect(() => serializeRpcResult({ a: 'x'.repeat(100) })).toThrow()
})

`resetInvokePolicy`

Clears registerPreInvoke hooks, audit hooks, and rate-limit buckets from configureInvokeRateLimit.


import { afterEach, it, expect } from 'vitest'
import {
  registerPreInvoke,
  resetInvokePolicy,
  configureInvokeRateLimit,
} from '@gloocan/cat-inspector'
 
afterEach(() => {
  resetInvokePolicy()
})
 
it('denies invoke when pre-invoke returns false', async () => {
  const unregister = registerPreInvoke(() => ({ allow: false }))
  // … call executeRPC or transport invoke; expect denial …
  unregister() // optional if you also reset in afterEach
  configureInvokeRateLimit(null)
})

`resetInvokeTimeoutMs`

Clears the global override from setInvokeTimeoutMs. Use after tests that shorten or lengthen the executeRPC wait without a full inspector reset.


import { afterEach, it } from 'vitest'
import { setInvokeTimeoutMs, resetInvokeTimeoutMs, executeRPC } from '@gloocan/cat-inspector'
 
afterEach(() => {
  resetInvokeTimeoutMs()
})
 
it('returns INVOKE_TIMEOUT when the handler is slow', async () => {
  setInvokeTimeoutMs(1)
  // … register a slow handler, await executeRPC, assert error code …
})

`resetSessionStore`

Clears in-memory session rows from sessionCreate / sessionStep. Use in tests that drive session wire messages without re-bootstrapping the registry.


import { beforeEach, it, expect } from 'vitest'
import { sessionCreate, sessionStep, resetSessionStore } from '@gloocan/cat-inspector'
 
beforeEach(() => {
  resetSessionStore()
})
 
it('creates a fresh session id each run', () => {
  const a = sessionCreate('user-1')
  const b = sessionCreate('user-1')
  expect(a.sessionId).not.toBe(b.sessionId)
})

`clearHttpBridgeRegistry`

Removes specs registered with registerHttpBridgeRoute. Use after tests that wire synthetic HTTP invoke (invokeKind: 'http_synthetic').


import { afterEach, beforeEach, it } from 'vitest'
import express from 'express'
import {
  registerHttpBridgeRoute,
  clearHttpBridgeRegistry,
  resetInspectorState,
} from '@gloocan/cat-inspector'
 
beforeEach(() => {
  resetInspectorState() // still needed if you populate Registry + register routes
})
 
afterEach(() => {
  clearHttpBridgeRegistry()
})
 
it('invokes via http_synthetic bridge', async () => {
  const app = express()
  // Registry.set(fnKey, { invokeKind: 'http_synthetic', … })
  registerHttpBridgeRoute(app, { fnKey: 'MyRoute', method: 'POST', path: '/x' })
  // … executeRPC(fnKey, …) …
})

If the suite both registers bridge routes and mutates the registry, call resetInspectorState() in beforeEach (it already includes clearHttpBridgeRegistry()).

Quick reference

Function	Clears	Typical placement
`resetInspectorState`	All global SDK state	`beforeEach` in RPC / bootstrap / transport suites
`resetParamsJsonSchemaValidators`	Params AJV cache	`beforeEach` in params-schema unit tests
`resetReturnJsonSchemaValidators`	Return AJV cache	`beforeEach` in return-schema unit tests
`resetRpcSerializationConfig`	Serialization toggles	`beforeEach` in `serializeRpcResult` tests
`resetInvokePolicy`	Pre-invoke, audit, rate limits	`afterEach` in policy / rate-limit tests
`resetInvokeTimeoutMs`	Global invoke timeout override	`afterEach` after `setInvokeTimeoutMs` tests
`resetSessionStore`	Session rows only	`beforeEach` in session wire tests
`clearHttpBridgeRegistry`	Synthetic HTTP bridge specs	`afterEach` when only bridges leak (else use full reset)

Rule of thumb: if unsure, use resetInspectorState() once per test.

Testing and resets

resetInspectorState() — default for integration tests

Granular resets — when you only touched one subsystem

resetParamsJsonSchemaValidators

resetReturnJsonSchemaValidators

resetRpcSerializationConfig

resetInvokePolicy

resetInvokeTimeoutMs

resetSessionStore

clearHttpBridgeRegistry