Skip to main content
Faremeter API
Faremeter API / test-harness/src

​
test-harness/src

​
Classes

​
TestHarness

Defined in: packages/test-harness/src/harness/harness.ts:47 TestHarness provides an in-process test environment for the x402 protocol. It connects client, middleware, and facilitator using function adapters instead of HTTP, allowing full protocol testing without network calls.

​
Constructors

Constructor
new TestHarness(config): TestHarness
Defined in: packages/test-harness/src/harness/harness.ts:64
Parameters
config
TestHarnessConfig
Returns
TestHarness

​
Properties

app
readonly app: Hono
Defined in: packages/test-harness/src/harness/harness.ts:51 The internal Hono app containing facilitator and middleware routes.

​
Methods

addClientInterceptor()
addClientInterceptor(interceptor): void
Defined in: packages/test-harness/src/harness/harness.ts:268 Add an interceptor to the client chain (between test code and middleware).
Parameters
interceptor
Interceptor
Returns
void
addMiddlewareInterceptor()
addMiddlewareInterceptor(interceptor): void
Defined in: packages/test-harness/src/harness/harness.ts:275 Add an interceptor to the middleware chain (between middleware and facilitator).
Parameters
interceptor
Interceptor
Returns
void
clearInterceptors()
clearInterceptors(): void
Defined in: packages/test-harness/src/harness/harness.ts:282 Clear all interceptors added after construction.
Returns
void
createFetch()
createFetch(opts?): {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }
Defined in: packages/test-harness/src/harness/harness.ts:196 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>
MDN Reference
Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
(input, init?): Promise<Response>
MDN Reference
Parameters
input
string | Request | URL
init?
RequestInit
Returns
Promise<Response>
reset()
reset(): void
Defined in: packages/test-harness/src/harness/harness.ts:292 Reset harness state (interceptors, resource handler).
Returns
void
setResourceHandler()
setResourceHandler(handler): void
Defined in: packages/test-harness/src/harness/harness.ts:185 Set the resource handler that responds after successful payment.
Parameters
handler
ResourceHandler
Returns
void

​
Type Aliases

​
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:30 Options for creating a test facilitator handler.

​
Properties

onSettle()?
optional onSettle: (requirements, payload, testPayload) => void
Defined in: packages/test-harness/src/scheme/facilitator.ts:40 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:34 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:32 Address that should receive payments.

​
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

​
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 = ResourceContextV1 | ResourceContextV2
Defined in: packages/test-harness/src/harness/resource.ts:48 Resource context passed to the resource handler after successful payment. Discriminated union based on protocolVersion.

​
ResourceContextV1

ResourceContextV1 = ResourceContextBase & object
Defined in: packages/test-harness/src/harness/resource.ts:25 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:36 Resource context for v2 protocol.

​
Type declaration

paymentPayload
paymentPayload: x402PaymentPayload
paymentRequirements
paymentRequirements: x402PaymentRequirements
protocolVersion
protocolVersion: 2
settleResponse
settleResponse: x402SettleResponse
verifyResponse?
optional verifyResponse: x402VerifyResponse

​
ResourceHandler()

ResourceHandler = (ctx) => ResourceResult | Promise<ResourceResult>
Defined in: packages/test-harness/src/harness/resource.ts:56

​
Parameters

ctx
ResourceContext

​
Returns

ResourceResult | Promise<ResourceResult>

​
ResourceResult

ResourceResult = object
Defined in: packages/test-harness/src/harness/resource.ts:50

​
Properties

body
body: unknown
Defined in: packages/test-harness/src/harness/resource.ts:52
headers?
optional headers: Record<string, string>
Defined in: packages/test-harness/src/harness/resource.ts:53
status
status: number
Defined in: packages/test-harness/src/harness/resource.ts:51

​
SettleMode

SettleMode = "settle-only" | "verify-then-settle"
Defined in: packages/test-harness/src/harness/config.ts:14 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 = object
Defined in: packages/test-harness/src/harness/config.ts:19 Configuration for TestHarness.

​
Properties

accepts
accepts: Partial<x402PaymentRequirements>[]
Defined in: packages/test-harness/src/harness/config.ts:24 Payment requirements the middleware accepts. Uses Partial because the facilitator will fill in missing fields.
clientHandlers
clientHandlers: PaymentHandlerV1[]
Defined in: packages/test-harness/src/harness/config.ts:37 Client payment handlers (v1). Internally adapted to v2 for use with the fetch client. Multiple handlers can be provided for different schemes.
clientInterceptors?
optional clientInterceptors: Interceptor[]
Defined in: packages/test-harness/src/harness/config.ts:55 Interceptors between test code and middleware. These see all requests from the wrapped fetch to the Hono app.
facilitatorHandlers
facilitatorHandlers: FacilitatorHandler[]
Defined in: packages/test-harness/src/harness/config.ts:30 Facilitator handlers to register. Multiple handlers can be provided for different schemes.
middlewareInterceptors?
optional middlewareInterceptors: Interceptor[]
Defined in: packages/test-harness/src/harness/config.ts:61 Interceptors between middleware and facilitator. These see requests from middleware to facilitator endpoints.
settleMode?
optional settleMode: SettleMode
Defined in: packages/test-harness/src/harness/config.ts:43 Settlement mode for the middleware.
Default
"settle-only"
supportedVersions?
optional supportedVersions: SupportedVersionsConfig
Defined in: packages/test-harness/src/harness/config.ts:49 Protocol versions the middleware should support. Passed through to middleware without modification.

​
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:78

​
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_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

​
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

Interceptor

​
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:65 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

​
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

Interceptor

​
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.

​
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

​
isResourceContextV1()

isResourceContextV1(ctx): ctx is ResourceContextV1
Defined in: packages/test-harness/src/harness/resource.ts:63 Type guard to check if context is v1.

​
Parameters

ctx
ResourceContext

​
Returns

ctx is ResourceContextV1

​
isResourceContextV2()

isResourceContextV2(ctx): ctx is ResourceContextV2
Defined in: packages/test-harness/src/harness/resource.ts:72 Type guard to check if context is v2.

​
Parameters

ctx
ResourceContext

​
Returns

ctx is ResourceContextV2

​
jsonResponse()

jsonResponse(status, body): Response
Defined in: packages/test-harness/src/interceptors/responses.ts:10 Creates a JSON Response with the given status and body.

​
Parameters

status
number HTTP status code.
body
object Object to serialize as JSON.

​
Returns

Response A Response with JSON content type.

​
matchMethod()

matchMethod(method): RequestMatcher
Defined in: packages/test-harness/src/interceptors/matchers.ts:72 Creates a matcher that checks the HTTP method.

​
Parameters

method
string HTTP method to match (case-insensitive).

​
Returns

RequestMatcher A matcher that succeeds if the request uses the specified method.

​
matchURL()

matchURL(pattern): RequestMatcher
Defined in: packages/test-harness/src/interceptors/matchers.ts:59 Creates a matcher that checks the URL against a pattern.

​
Parameters

pattern
String to search for or RegExp to test. string | RegExp

​
Returns

RequestMatcher A matcher that succeeds if the URL matches the pattern.

​
networkError()

networkError(message): Error
Defined in: packages/test-harness/src/interceptors/responses.ts:139 Creates a network error for testing error handling.

​
Parameters

message
string = "Network error" Error message.

​
Returns

Error An Error to be thrown by interceptors.

​
not()

not(matcher): RequestMatcher
Defined in: packages/test-harness/src/interceptors/matchers.ts:49 Negates a matcher.

​
Parameters

matcher
RequestMatcher Matcher to negate.

​
Returns

RequestMatcher A matcher that succeeds when the provided matcher fails.

​
or()

or(…matchers): RequestMatcher
Defined in: packages/test-harness/src/interceptors/matchers.ts:39 Combines matchers with logical OR: any must match.

​
Parameters

matchers
…RequestMatcher[] Matchers to combine.

​
Returns

RequestMatcher A matcher that succeeds if any provided matcher succeeds.

​
paymentRequiredResponse()

paymentRequiredResponse(accepts, error): Response
Defined in: packages/test-harness/src/interceptors/responses.ts:122 Creates a 402 Payment Required response.

​
Parameters

accepts
object[] Payment requirements the server accepts.
error
string = "" Optional error message.

​
Returns

Response A 402 Response with x402Version: 1.

​
settleFailedResponse()

settleFailedResponse(errorReason): Response
Defined in: packages/test-harness/src/interceptors/responses.ts:49 Creates a failed settle response (v1 format).

​
Parameters

errorReason
string Reason for settlement failure.

​
Returns

Response A 200 Response with success: false.

​
settleFailedResponseV2()

settleFailedResponseV2(errorReason, network): Response
Defined in: packages/test-harness/src/interceptors/responses.ts:66 Creates a failed settle response (v2 format).

​
Parameters

errorReason
string Reason for settlement failure.
network
string Network identifier for the response.

​
Returns

Response A 200 Response with success: false.

​
settleSuccessResponse()

settleSuccessResponse(transaction, network): Response
Defined in: packages/test-harness/src/interceptors/responses.ts:85 Creates a successful settle response (v1 format).

​
Parameters

transaction
string Transaction identifier.
network
string Network identifier.

​
Returns

Response A 200 Response with success: true.

​
settleSuccessResponseV2()

settleSuccessResponseV2(transaction, network): Response
Defined in: packages/test-harness/src/interceptors/responses.ts:104 Creates a successful settle response (v2 format).

​
Parameters

transaction
string Transaction identifier.
network
string Network identifier.

​
Returns

Response A 200 Response with success: true.

​
suppressConsoleErrors()

suppressConsoleErrors(): () => void
Defined in: packages/test-harness/src/testing/console.ts:10 Suppresses console.error output during tests. Returns a restore function to be called in teardown. Usage with tap: t.teardown(suppressConsoleErrors());

​
Returns

(): void
Returns
void

​
timeoutError()

timeoutError(): Error
Defined in: packages/test-harness/src/interceptors/responses.ts:148 Creates a timeout error for testing timeout handling.

​
Returns

Error An Error with “Request timed out” message.

​
verifyFailedResponse()

verifyFailedResponse(reason): Response
Defined in: packages/test-harness/src/interceptors/responses.ts:23 Creates a failed verify response.

​
Parameters

reason
string Reason for verification failure.

​
Returns

Response A 200 Response with isValid: false.

​
verifySuccessResponse()

verifySuccessResponse(): Response
Defined in: packages/test-harness/src/interceptors/responses.ts:36 Creates a successful verify response.

​
Returns

Response A 200 Response with isValid: true.