Test Harness Package

Returns

void

addHandlerInterceptor()

addHandlerInterceptor(interceptor): void

Defined in: packages/test-harness/src/harness/harness.ts:382

Parameters

interceptor

HandlerInterceptor

Returns

void

addMiddlewareInterceptor()

addMiddlewareInterceptor(interceptor): void

Defined in: packages/test-harness/src/harness/harness.ts:373 Add an interceptor to the middleware chain (between middleware and facilitator).

Parameters

interceptor

Returns

void

clearInterceptors()

clearInterceptors(): void

Defined in: packages/test-harness/src/harness/harness.ts:394 Clear all interceptors added after construction.

Returns

void

createClientFetch()

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

Defined in: packages/test-harness/src/harness/harness.ts:259 Create a fetch function for client->middleware calls. This applies client interceptors and routes to the Hono app.

Returns

(input, init?): Promise<Response>

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

(input, init?): Promise<Response>

Parameters

input

string | Request | URL

init?

RequestInit

Returns

Promise<Response>

(input, init?): Promise<Response>

Parameters

input

string | Request | URL

init?

RequestInit

Returns

Promise<Response>

createFetch()

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

Defined in: packages/test-harness/src/harness/harness.ts:292 Create a fetch function that handles the full x402 payment flow.

Parameters

opts?

payerChooser?

(execers) => PaymentExecerV1 | Promise<PaymentExecerV1> Function to choose which payment option to use. Receives v1 PaymentExecerV1[] for compatibility with v1 protocol tests. The chosen execer is converted back to v2 internally.

Returns

(input, init?): Promise<Response>

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

(input, init?): Promise<Response>

Parameters

input

string | Request | URL

init?

RequestInit

Returns

Promise<Response>

(input, init?): Promise<Response>

Parameters

input

string | Request | URL

init?

RequestInit

Returns

Promise<Response>

reset()

reset(): void

Defined in: packages/test-harness/src/harness/harness.ts:410 Reset harness state (interceptors, resource handler).

Returns

void

setResourceHandler()

setResourceHandler(handler): void

Defined in: packages/test-harness/src/harness/harness.ts:281 Set the resource handler that responds after successful payment.

Parameters

handler

ResourceHandler

Returns

void

Type Aliases

AmountPolicy()

AmountPolicy = (settleAmount, signedAmount) => boolean

Defined in: packages/test-harness/src/scheme/facilitator.ts:34 Policy that decides whether a settlement amount is acceptable given the signed payment amount. The default is exact match.

Parameters

settleAmount

bigint

signedAmount

bigint

Returns

boolean

CreateSimpleFacilitatorHandlerOpts

CreateSimpleFacilitatorHandlerOpts = object

Defined in: packages/test-harness/src/test-handlers.ts:139 Options for creating a simple facilitator handler.

Properties

getSupported()?

optional getSupported: () => Promise<x402SupportedKind>[]

Defined in: packages/test-harness/src/test-handlers.ts:143 Optional function returning supported payment kinds.

Returns

Promise<x402SupportedKind>[]

networkId

networkId: string

Defined in: packages/test-harness/src/test-handlers.ts:141 Network identifier for settle responses.

CreateTestFacilitatorHandlerOpts

CreateTestFacilitatorHandlerOpts = object

Defined in: packages/test-harness/src/scheme/facilitator.ts:39

Properties

amountPolicy?

optional amountPolicy: AmountPolicy

Defined in: packages/test-harness/src/scheme/facilitator.ts:48 Decides whether a settlement amount is acceptable given the signed payment amount. Defaults to exact match. Tests for hold-and-settle schemes should pass (settle, signed) => settle <= signed.

onSettle()?

optional onSettle: (requirements, payload, testPayload) => void

Defined in: packages/test-harness/src/scheme/facilitator.ts:56 Optional callback invoked during settle.

Parameters

requirements

x402PaymentRequirements

payload

x402PaymentPayload

testPayload

TestPaymentPayload

Returns

void

onVerify()?

optional onVerify: (requirements, payload, testPayload) => void

Defined in: packages/test-harness/src/scheme/facilitator.ts:50 Optional callback invoked during verify.

Parameters

requirements

x402PaymentRequirements

payload

x402PaymentPayload

testPayload

TestPaymentPayload

Returns

void

payTo

payTo: string

Defined in: packages/test-harness/src/scheme/facilitator.ts:41 Address that should receive payments.

CreateTestMPPHandlerOpts

CreateTestMPPHandlerOpts = object

Defined in: packages/test-harness/src/scheme/mpp.ts:47

Properties

intents?

optional intents: string[]

Defined in: packages/test-harness/src/scheme/mpp.ts:50

method?

optional method: string

Defined in: packages/test-harness/src/scheme/mpp.ts:48

onChallenge()?

optional onChallenge: (intent, pricing, resourceURL) => void

Defined in: packages/test-harness/src/scheme/mpp.ts:51

Parameters

intent

string

pricing

ResourcePricing

resourceURL

string

Returns

void

onSettle()?

optional onSettle: (credential) => void

Defined in: packages/test-harness/src/scheme/mpp.ts:56

Parameters

credential

mppCredential

Returns

void

realm?

optional realm: string

Defined in: packages/test-harness/src/scheme/mpp.ts:49

CreateTestMPPPaymentHandlerOpts

CreateTestMPPPaymentHandlerOpts = object

Defined in: packages/test-harness/src/scheme/mpp.ts:121

Properties

intent?

optional intent: string

Defined in: packages/test-harness/src/scheme/mpp.ts:123

method?

optional method: string

Defined in: packages/test-harness/src/scheme/mpp.ts:122

onExec()?

optional onExec: (challenge) => void

Defined in: packages/test-harness/src/scheme/mpp.ts:125

Parameters

challenge

mppChallengeParams

Returns

void

onMatch()?

optional onMatch: (challenge) => void

Defined in: packages/test-harness/src/scheme/mpp.ts:124

Parameters

challenge

mppChallengeParams

Returns

void

CreateTestPaymentHandlerOpts

CreateTestPaymentHandlerOpts = object

Defined in: packages/test-harness/src/scheme/client.ts:15 Options for creating a test payment handler.

Properties

metadata?

optional metadata: Record<string, unknown>

Defined in: packages/test-harness/src/scheme/client.ts:24 Custom metadata to include in test payloads.

onExec()?

optional onExec: (requirements, payload) => void

Defined in: packages/test-harness/src/scheme/client.ts:19 Optional callback when payment is executed.

Parameters

requirements

x402PaymentRequirements

payload

TestPaymentPayload

Returns

void

onMatch()?

optional onMatch: (requirements) => void

Defined in: packages/test-harness/src/scheme/client.ts:17 Optional callback when requirements are matched.

Parameters

requirements

x402PaymentRequirements

Returns

void

HandlerInterceptor()

HandlerInterceptor = (handler) => FacilitatorHandler

Defined in: packages/test-harness/src/interceptors/types.ts:49 A function that wraps a FacilitatorHandler to intercept handler method calls. Used for in-process handler testing where there is no HTTP layer to intercept.

Parameters

handler

FacilitatorHandler

Returns

FacilitatorHandler

HTTPConfig

HTTPConfig = BaseConfig & object

Defined in: packages/test-harness/src/harness/config.ts:44 Configuration for HTTP facilitator testing. The test harness mounts facilitator routes and the middleware communicates via HTTP.

Type declaration

accepts

accepts: Partial<x402PaymentRequirements>[]

facilitatorHandlers

facilitatorHandlers: FacilitatorHandler[]

middlewareInterceptors?

optional middlewareInterceptors: Interceptor[]

InProcessConfig

InProcessConfig = BaseConfig & object

Defined in: packages/test-harness/src/harness/config.ts:33 Configuration for in-process handler testing. Handlers run directly in the middleware with no facilitator HTTP service.

Type declaration

handlerInterceptors?

optional handlerInterceptors: HandlerInterceptor[]

mppMethodHandlers?

optional mppMethodHandlers: MPPMethodHandler[]

pricing

pricing: ResourcePricing[]

x402Handlers?

optional x402Handlers: FacilitatorHandler[]

Interceptor()

Interceptor = (fetch) => typeof globalThis.fetch

Defined in: packages/test-harness/src/interceptors/types.ts:7 A function that wraps fetch to intercept requests and responses. Interceptors can modify requests before they’re sent, inspect or modify responses, inject failures, add delays, or log activity.

Parameters

fetch

typeof globalThis.fetch

Returns

typeof globalThis.fetch

LogEvent

LogEvent = object

Defined in: packages/test-harness/src/interceptors/logging.ts:7 Event emitted by logging interceptors for requests, responses, and errors.

Properties

error?

optional error: string

Defined in: packages/test-harness/src/interceptors/logging.ts:12

method?

optional method: string

Defined in: packages/test-harness/src/interceptors/logging.ts:10

status?

optional status: number

Defined in: packages/test-harness/src/interceptors/logging.ts:11

timestamp

timestamp: number

Defined in: packages/test-harness/src/interceptors/logging.ts:13

type

type: "request" | "response" | "error"

Defined in: packages/test-harness/src/interceptors/logging.ts:8

url

url: string

Defined in: packages/test-harness/src/interceptors/logging.ts:9

RequestMatcher()

RequestMatcher = (url, init?) => boolean

Defined in: packages/test-harness/src/interceptors/types.ts:42 Predicate function that determines whether a request should be matched. Used by interceptors to selectively apply behavior to specific requests.

Parameters

url

string

init?

RequestInit

Returns

boolean

ResourceContext

ResourceContext = ResourceContextX402 | ResourceContextMPP

Defined in: packages/test-harness/src/harness/resource.ts:64 Resource context passed to the resource handler after successful payment. Discriminated union based on protocolVersion.

ResourceContextMPP

ResourceContextMPP = ResourceContextBase & object

Defined in: packages/test-harness/src/harness/resource.ts:48 Resource context for MPP protocol.

Type declaration

credential

credential: mppCredential

protocolVersion

protocolVersion: "mpp"

receipt

receipt: mppReceipt

ResourceContextV1

ResourceContextV1 = ResourceContextBase & object

Defined in: packages/test-harness/src/harness/resource.ts:26 Resource context for v1 protocol.

Type declaration

paymentPayload

paymentPayload: x402PaymentPayloadV1

paymentRequirements

paymentRequirements: x402PaymentRequirementsV1

protocolVersion

protocolVersion: 1

settleResponse

settleResponse: x402SettleResponseV1

verifyResponse?

optional verifyResponse: x402VerifyResponseV1

ResourceContextV2

ResourceContextV2 = ResourceContextBase & object

Defined in: packages/test-harness/src/harness/resource.ts:37 Resource context for v2 protocol.

Type declaration

paymentPayload

paymentPayload: x402PaymentPayload

paymentRequirements

paymentRequirements: x402PaymentRequirements

protocolVersion

protocolVersion: 2

settleResponse

settleResponse: x402SettleResponse

verifyResponse?

optional verifyResponse: x402VerifyResponse

ResourceContextX402

ResourceContextX402 = ResourceContextV1 | ResourceContextV2

Defined in: packages/test-harness/src/harness/resource.ts:58 Resource context for x402 protocols (v1 or v2). Use when the handler only needs to work with x402 payment fields.

ResourceHandler()

ResourceHandler = (ctx) => ResourceResult | Promise<ResourceResult>

Defined in: packages/test-harness/src/harness/resource.ts:72

Parameters

ctx

Returns

ResourceResult | Promise<ResourceResult>

ResourceResult

ResourceResult = object

Defined in: packages/test-harness/src/harness/resource.ts:66

Properties

body

body: unknown

Defined in: packages/test-harness/src/harness/resource.ts:68

headers?

optional headers: Record<string, string>

Defined in: packages/test-harness/src/harness/resource.ts:69

status

status: number

Defined in: packages/test-harness/src/harness/resource.ts:67

SettleMode

SettleMode = "settle-only" | "verify-then-settle"

Defined in: packages/test-harness/src/harness/config.ts:16 How the middleware handles payment verification and settlement.

"settle-only" - Skip verification, settle directly (faster tests).
"verify-then-settle" - Verify payment before settling (more realistic).

TestHarnessConfig

TestHarnessConfig = InProcessConfig | HTTPConfig

Defined in: packages/test-harness/src/harness/config.ts:53 Configuration for TestHarness.

TestPaymentPayload

TestPaymentPayload = object

Defined in: packages/test-harness/src/scheme/types.ts:4 Payload structure for test payment scheme transactions.

Properties

amount

amount: string

Defined in: packages/test-harness/src/scheme/types.ts:6

metadata?

optional metadata: Record<string, unknown>

Defined in: packages/test-harness/src/scheme/types.ts:8

testId

testId: string

Defined in: packages/test-harness/src/scheme/types.ts:5

timestamp

timestamp: number

Defined in: packages/test-harness/src/scheme/types.ts:7

Variables

defaultResourceHandler

const defaultResourceHandler: ResourceHandler

Defined in: packages/test-harness/src/harness/resource.ts:100

matchAll

const matchAll: RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:77

matchFacilitator

const matchFacilitator: RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:15

matchFacilitatorAccepts

const matchFacilitatorAccepts: RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:3

matchFacilitatorSettle

const matchFacilitatorSettle: RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:9

matchFacilitatorSupported

const matchFacilitatorSupported: RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:12

matchFacilitatorVerify

const matchFacilitatorVerify: RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:6

matchNone

const matchNone: RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:78

matchResource

const matchResource: RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:21

TEST_ASSET

const TEST_ASSET: "TEST" = "TEST"

Defined in: packages/test-harness/src/scheme/constants.ts:3

TEST_MPP_INTENT

const TEST_MPP_INTENT: "charge" = "charge"

Defined in: packages/test-harness/src/scheme/mpp.ts:16

TEST_MPP_METHOD

const TEST_MPP_METHOD: "test-solana" = "test-solana"

Defined in: packages/test-harness/src/scheme/mpp.ts:15

TEST_MPP_REALM

const TEST_MPP_REALM: "test-realm" = "test-realm"

Defined in: packages/test-harness/src/scheme/mpp.ts:17

TEST_NETWORK

const TEST_NETWORK: "test-local" = "test-local"

Defined in: packages/test-harness/src/scheme/constants.ts:2

TEST_SCHEME

const TEST_SCHEME: "test" = "test"

Defined in: packages/test-harness/src/scheme/constants.ts:1

Functions

accepts()

accepts(overrides?): object

Defined in: packages/test-harness/src/harness/defaults.ts:10 Creates a payment requirements object with test defaults (v1 format). Override specific fields by passing a partial: accepts({ maxAmountRequired: “500” })

Parameters

overrides?

Partial<{ asset: string; description: string; extra?: object; maxAmountRequired: string; maxTimeoutSeconds: number; mimeType?: string; network: string; outputSchema?: object; payTo: string; resource: string; scheme: string; }>

Returns

object

asset

asset: string

description

description: string

extra?

optional extra: object

maxAmountRequired

maxAmountRequired: string

maxTimeoutSeconds

maxTimeoutSeconds: number

mimeType?

optional mimeType: string

network

network: string

outputSchema?

optional outputSchema: object

payTo

payTo: string

resource

resource: string

scheme

scheme: string

acceptsV2()

acceptsV2(overrides?): object

Defined in: packages/test-harness/src/harness/defaults.ts:32 Creates a payment requirements object with test defaults (v2 format). Override specific fields by passing a partial: acceptsV2({ amount: “500” })

Parameters

overrides?

Partial<{ amount: string; asset: string; extra?: object; maxTimeoutSeconds: number; network: string; payTo: string; scheme: string; }>

Returns

object

amount

amount: string

asset

asset: string

extra?

optional extra: object

maxTimeoutSeconds

maxTimeoutSeconds: number

network

network: string

payTo

payTo: string

scheme

scheme: string

and()

and(…matchers): RequestMatcher

Defined in: packages/test-harness/src/interceptors/matchers.ts:29 Combines matchers with logical AND: all must match.

Parameters

matchers

…RequestMatcher[] Matchers to combine.

Returns

RequestMatcher A matcher that succeeds only if all provided matchers succeed.

chooseByAsset()

chooseByAsset(asset): (execers) => PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:68 Creates a chooser that selects by asset name.

Parameters

asset

string Asset name to match (case-insensitive).

Returns

A chooser function.

(execers): PaymentExecerV1

Parameters

execers

PaymentExecerV1[]

Returns

PaymentExecerV1

chooseByIndex()

chooseByIndex(index): (execers) => PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:128 Creates a chooser that selects by array index.

Parameters

index

number Zero-based index of the option to select.

Returns

A chooser function.

(execers): PaymentExecerV1

Parameters

execers

PaymentExecerV1[]

Returns

PaymentExecerV1

chooseByNetwork()

chooseByNetwork(network): (execers) => PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:88 Creates a chooser that selects by network name.

Parameters

network

string Network name to match (case-insensitive).

Returns

A chooser function.

(execers): PaymentExecerV1

Parameters

execers

PaymentExecerV1[]

Returns

PaymentExecerV1

chooseByScheme()

chooseByScheme(scheme): (execers) => PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:108 Creates a chooser that selects by payment scheme.

Parameters

scheme

string Scheme name to match (case-insensitive).

Returns

A chooser function.

(execers): PaymentExecerV1

Parameters

execers

PaymentExecerV1[]

Returns

PaymentExecerV1

chooseCheapest()

chooseCheapest(execers): PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:29 Chooser that selects the cheapest payment option by maxAmountRequired.

Parameters

execers

PaymentExecerV1[] Available payment execers.

Returns

PaymentExecerV1 The execer with the lowest amount.

Throws

If no options are available.

chooseFirst()

chooseFirst(execers): PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:11 Chooser that selects the first available payment option.

Parameters

execers

PaymentExecerV1[] Available payment execers.

Returns

PaymentExecerV1 The first execer in the list.

Throws

If no options are available.

chooseMostExpensive()

chooseMostExpensive(execers): PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:48 Chooser that selects the most expensive payment option by maxAmountRequired.

Parameters

execers

PaymentExecerV1[] Available payment execers.

Returns

PaymentExecerV1 The execer with the highest amount.

Throws

If no options are available.

chooseNone()

chooseNone(): never

Defined in: packages/test-harness/src/choosers.ts:147 Chooser that always throws, useful for testing “no suitable option” paths.

Returns

never

Throws

Always throws “No suitable payment option”.

chooseWithFilter()

chooseWithFilter(filter, inner): (execers) => PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:175 Wraps a chooser to filter options before choosing.

Parameters

filter

(execer) => boolean Predicate to filter available options.

inner

(execers) => PaymentExecerV1 Chooser to delegate to after filtering.

Returns

A chooser that filters then delegates.

(execers): PaymentExecerV1

Parameters

execers

PaymentExecerV1[]

Returns

PaymentExecerV1

chooseWithInspection()

chooseWithInspection(inspector, inner): (execers) => PaymentExecerV1

Defined in: packages/test-harness/src/choosers.ts:158 Wraps a chooser to inspect options before choosing.

Parameters

inspector

(execers) => void Callback to inspect available options.

inner

(execers) => PaymentExecerV1 Chooser to delegate to after inspection.

Returns

A chooser that inspects then delegates.

(execers): PaymentExecerV1

Parameters

execers

PaymentExecerV1[]

Returns

PaymentExecerV1

composeHandlerInterceptors()

composeHandlerInterceptors(…interceptors): HandlerInterceptor

Defined in: packages/test-harness/src/interceptors/types.ts:60 Compose multiple handler interceptors into a single interceptor. Interceptors are applied right-to-left (last interceptor wraps innermost). This means the first interceptor in the array sees calls first and results last, matching the semantics of composeInterceptors.

Parameters

interceptors

…HandlerInterceptor[]

Returns

HandlerInterceptor

composeInterceptors()

composeInterceptors(…interceptors): Interceptor

Defined in: packages/test-harness/src/interceptors/types.ts:27 Compose multiple interceptors into a single interceptor. Interceptors are applied right-to-left (last interceptor wraps innermost). This means the first interceptor in the array sees the request first and the response last.

Parameters

interceptors

…Interceptor[]

Returns

Example

const composed = composeInterceptors(
  loggingInterceptor,    // Sees request first, response last
  failureInterceptor,    // Sees request second
  delayInterceptor,      // Innermost - closest to actual fetch
);

createCaptureInterceptor()

createCaptureInterceptor(match): object

Defined in: packages/test-harness/src/interceptors/hooks.ts:101 Creates an interceptor that captures matching requests for later inspection.

Parameters

match

RequestMatcher Predicate to determine which requests to capture.

Returns

object Object with the interceptor, captured array, and clear function.

captured

captured: CapturedRequest[]

clear()

clear: () => void

Returns

void

interceptor

interceptor: Interceptor

createConsoleLoggingInterceptor()

createConsoleLoggingInterceptor(prefix, log): Interceptor

Defined in: packages/test-harness/src/interceptors/logging.ts:69 Creates an interceptor that logs to the console with a prefix.

Parameters

prefix

string = "[test-harness]" Prefix for log messages.

log

Logger with log and error methods (defaults to console).

error

(msg) => void

log

(msg) => void

Returns

Interceptor An interceptor that logs to console.

createDelayInterceptor()

createDelayInterceptor(match, delayMs): Interceptor

Defined in: packages/test-harness/src/interceptors/delay.ts:11 Creates an interceptor that delays matching requests before sending.

Parameters

match

RequestMatcher Predicate to determine which requests to delay.

delayMs

number Delay in milliseconds.

Returns

Interceptor An interceptor that adds request delay.

createEmptyPayloadHandler()

createEmptyPayloadHandler(): PaymentHandlerV1

Defined in: packages/test-harness/src/test-handlers.ts:80 Creates a payment handler that returns an empty payload object.

Returns

PaymentHandlerV1

createEventCollector()

createEventCollector(): object

Defined in: packages/test-harness/src/interceptors/logging.ts:92 Creates an interceptor that collects events into an array for assertions.

Returns

object Object with the interceptor, events array, and clear function.

clear()

clear: () => void

Returns

void

events

events: LogEvent[]

interceptor

interceptor: Interceptor

createFailureInterceptor()

createFailureInterceptor(match, failFn): Interceptor

Defined in: packages/test-harness/src/interceptors/failures.ts:11 Creates an interceptor that fails matching requests.

Parameters

match

RequestMatcher Predicate to determine which requests to fail.

failFn

() => Response | Error | Promise<Response | Error> Function returning the failure (Response or Error).

Returns

Interceptor An interceptor that fails matching requests.

createHook()

createHook(match, hooks): Interceptor

Defined in: packages/test-harness/src/interceptors/hooks.ts:60 Creates an interceptor with both request and response hooks.

Parameters

match

RequestMatcher Predicate to determine which requests to hook.

hooks

Object with optional onRequest and onResponse callbacks.

onRequest?

(url, init?) => void | Promise<void>

onResponse?

(url, response, init?) => void | Promise<void>

Returns

Interceptor An interceptor with both-side hooks.

createInvalidPayloadHandler()

createInvalidPayloadHandler(payloadFactory): PaymentHandlerV1

Defined in: packages/test-harness/src/test-handlers.ts:120 Creates a payment handler with a custom payload factory. Useful for testing invalid/edge-case payloads.

Parameters

payloadFactory

(requirements) => object

Returns

PaymentHandlerV1

createLoggingInterceptor()

createLoggingInterceptor(log): Interceptor

Defined in: packages/test-harness/src/interceptors/logging.ts:22 Creates an interceptor that logs all requests, responses, and errors.

Parameters

log

(event) => void Callback to receive log events.

Returns

Interceptor An interceptor that logs activity.

createNonMatchingHandler()

createNonMatchingHandler(): PaymentHandlerV1

Defined in: packages/test-harness/src/test-handlers.ts:21 Creates a payment handler that returns no matching execers. Useful for testing “no handler matches” scenarios.

Returns

PaymentHandlerV1

createNullPayloadHandler()

createNullPayloadHandler(): PaymentHandlerV1

Defined in: packages/test-harness/src/test-handlers.ts:62 Creates a payment handler that returns null payload.

Returns

PaymentHandlerV1

createRequestHook()

createRequestHook(match, hook): Interceptor

Defined in: packages/test-harness/src/interceptors/hooks.ts:11 Creates an interceptor that calls a hook before matching requests.

Parameters

match

RequestMatcher Predicate to determine which requests to hook.

hook

(url, init?) => void | Promise<void> Callback invoked before the request is sent.

Returns

Interceptor An interceptor with request-side hooks.

createResponseDelayInterceptor()

createResponseDelayInterceptor(match, delayMs): Interceptor

Defined in: packages/test-harness/src/interceptors/delay.ts:33 Creates an interceptor that delays matching responses after receiving.

Parameters

match

RequestMatcher Predicate to determine which responses to delay.

delayMs

number Delay in milliseconds.

Returns

Interceptor An interceptor that adds response delay.

createResponseHook()

createResponseHook(match, hook): Interceptor

Defined in: packages/test-harness/src/interceptors/hooks.ts:33 Creates an interceptor that calls a hook after matching responses.

Parameters

match

RequestMatcher Predicate to determine which responses to hook.

hook

(url, response, init?) => void | Promise<void> Callback invoked after the response is received.

Returns

Interceptor An interceptor with response-side hooks.

createSimpleFacilitatorHandler()

createSimpleFacilitatorHandler(opts): FacilitatorHandler

Defined in: packages/test-harness/src/test-handlers.ts:150 Creates a minimal facilitator handler for testing. Useful for testing /supported endpoint behavior.

Parameters

opts

CreateSimpleFacilitatorHandlerOpts

Returns

FacilitatorHandler

createTestFacilitatorHandler()

createTestFacilitatorHandler(opts): FacilitatorHandler

Defined in: packages/test-harness/src/scheme/facilitator.ts:81 Create a test facilitator handler. This handler validates protocol structure without any cryptographic operations, making it suitable for testing the x402 protocol flow.

Parameters

opts

CreateTestFacilitatorHandlerOpts

Returns

FacilitatorHandler

createTestMPPHandler()

createTestMPPHandler(opts): MPPMethodHandler

Defined in: packages/test-harness/src/scheme/mpp.ts:59

Parameters

opts

CreateTestMPPHandlerOpts = {}

Returns

MPPMethodHandler

createTestMPPPaymentHandler()

createTestMPPPaymentHandler(opts): MPPPaymentHandler

Defined in: packages/test-harness/src/scheme/mpp.ts:128

Parameters

opts

CreateTestMPPPaymentHandlerOpts = {}

Returns

MPPPaymentHandler

createTestPaymentHandler()

createTestPaymentHandler(opts): PaymentHandlerV1

Defined in: packages/test-harness/src/scheme/client.ts:33 Create a test payment handler. This handler creates simple test payment payloads without any cryptographic operations, making it suitable for testing the x402 protocol flow.

Parameters

opts

CreateTestPaymentHandlerOpts = {}

Returns

PaymentHandlerV1

createThrowingExecHandler()

createThrowingExecHandler(message): PaymentHandlerV1

Defined in: packages/test-harness/src/test-handlers.ts:45 Creates a payment handler that throws during exec().

Parameters

message

string

Returns

PaymentHandlerV1

createThrowingHandler()

createThrowingHandler(message): PaymentHandlerV1

Defined in: packages/test-harness/src/test-handlers.ts:33 Creates a payment handler that throws during the match phase.

Parameters

message

string

Returns

PaymentHandlerV1

createV2ResponseInterceptor()

createV2ResponseInterceptor(): Interceptor

Defined in: packages/test-harness/src/interceptors/v2.ts:20 Creates an interceptor that transforms v1 402 responses to v2 format. This allows testing v2 client behavior by making the middleware appear to respond with v2 format even though it defaults to v1. The transformation:

Parses the JSON body as v1 PaymentRequiredResponse
Converts to v2 PaymentRequiredResponse format
Encodes as base64 in PAYMENT-REQUIRED header
Returns 402 with the new header

Returns

createVariableDelayInterceptor()

createVariableDelayInterceptor(match, getDelay): Interceptor

Defined in: packages/test-harness/src/interceptors/delay.ts:56 Creates an interceptor with variable delay based on request context.

Parameters

match

RequestMatcher Predicate to determine which requests to delay.

getDelay

(url, init?) => number Function returning delay in ms for each request.

Returns

Interceptor An interceptor with dynamic delay.

createWorkingHandler()

createWorkingHandler(): PaymentHandlerV1

Defined in: packages/test-harness/src/test-handlers.ts:98 Creates a payment handler that works correctly. Useful for fallback testing scenarios.

Returns

PaymentHandlerV1

failNTimes()

failNTimes(n, match, failFn): Interceptor

Defined in: packages/test-harness/src/interceptors/failures.ts:63 Creates an interceptor that fails the first N matching requests.

Parameters

n

number Number of times to fail before passing through.

match

RequestMatcher Predicate to determine which requests to fail.

failFn

() => Response | Error Function returning the failure.

Returns

Interceptor An interceptor that fails N times then passes through.

failOnce()

failOnce(match, failFn): Interceptor

Defined in: packages/test-harness/src/interceptors/failures.ts:37 Creates an interceptor that fails the first matching request only.

Parameters

match

RequestMatcher Predicate to determine which requests to fail.

failFn

() => Response | Error Function returning the failure.

Returns

Interceptor An interceptor that fails once then passes through.

failUntilCleared()

failUntilCleared(match, failFn): Interceptor & object

Defined in: packages/test-harness/src/interceptors/failures.ts:91 Creates an interceptor that fails until manually cleared. Call clear() on the returned interceptor to stop failing.

Parameters

match

RequestMatcher Predicate to determine which requests to fail.

failFn

() => Response | Error Function returning the failure.

Returns

Interceptor & object An interceptor with a clear() method.

failWhen()

failWhen(match, shouldFail, failFn): Interceptor

Defined in: packages/test-harness/src/interceptors/failures.ts:120 Creates an interceptor that fails based on a dynamic condition. The condition receives the URL and attempt count, allowing patterns like “fail every other request” or “fail first 3 attempts”.

Parameters

match

RequestMatcher Predicate to determine which requests to consider.

shouldFail

(ctx) => boolean Condition that receives context with attempt count.

failFn

() => Response | Error Function returning the failure.

Returns

Interceptor An interceptor with conditional failure logic.

generateTestId()

generateTestId(): string

Defined in: packages/test-harness/src/scheme/types.ts:16 Generates a unique test payment identifier.

Returns

string A string like “test-1234567890-abc123”.

getURLFromRequestInfo()

getURLFromRequestInfo(input): string

Defined in: packages/test-harness/src/interceptors/utils.ts:7 Extracts the URL string from various request input types.

Parameters

input

A URL string, URL object, or Request object. RequestInfo | URL

Returns

string The URL as a string.

httpError()

httpError(status, message): Response

Defined in: packages/test-harness/src/interceptors/responses.ts:159 Creates an HTTP error response.

Parameters

status

number HTTP status code.

message

string Error message.

Returns

Response A Response with the error JSON body.

isInProcessConfig()

isInProcessConfig(config): config is InProcessConfig

Defined in: packages/test-harness/src/harness/config.ts:58 Type guard for in-process handler configuration.

Parameters

config

TestHarnessConfig

Returns

config is InProcessConfig

isMatchingRequirement()

isMatchingRequirement(req): boolean

Defined in: packages/test-harness/src/scheme/constants.ts:8 Checks if a payment requirement matches the test scheme and network.

Parameters

req

network

string

scheme

string

Returns

boolean

isResourceContextMPP()

isResourceContextMPP(ctx): ctx is ResourceContextMPP

Defined in: packages/test-harness/src/harness/resource.ts:94

Parameters

ctx

Returns

ctx is ResourceContextMPP

isResourceContextV1()

isResourceContextV1(ctx): ctx is ResourceContextV1

Defined in: packages/test-harness/src/harness/resource.ts:79 Type guard to check if context is v1.

Parameters

ctx

Returns

ctx is ResourceContextV1

isResourceContextV2()

isResourceContextV2(ctx): ctx is ResourceContextV2

Defined in: packages/test-harness/src/harness/resource.ts:88 Type guard to check if context is v2.

Parameters

ctx