Crate pdk_unit 

pdk-unit

A unit testing framework for PDK (Policy Development Kit) policies that enables testing Flex Gateway policies without requiring a running Envoy proxy or WebAssembly runtime.

Overview

pdk-unit provides a complete in-process testing solution for PDK policies by stubbing the Proxy-Wasm host environment. This allows developers to write fast, deterministic unit tests that verify policy behavior without the overhead of integration testing.

Quick Start

use pdk_unit::{UnitHttpRequest, UnitHttpResponse, UnitHttpMessage, UnitTestBuilder};

#[test]
fn test_my_policy() {
    let mut tester = UnitTestBuilder::default()
        .with_config(r#"{"key": "value"}"#)
        .with_entrypoint(crate::configure);

    let request = UnitHttpRequest::get()
        .with_header(":path", "/api/test");

    let response = tester.request(request);

    assert_eq!(response.status_code(), 200);
}

Core Components

• UnitTestBuilder - Fluent builder for configuring test instances
• UnitTest - Main test orchestrator managing request lifecycles
• UnitTestRequest - Handle to an in-flight request being processed
• UnitHttpRequest - HTTP request with method constructors (e.g. UnitHttpRequest::get)
• UnitHttpResponse - HTTP response with a status_code accessor
• UnitHttpMessage - Trait providing common read accessors for both request and response

Backends

Mock upstream services using the Backend and GrpcBackend traits:

• TraceBackend - Records all incoming requests for later inspection; also acts as a configurable response backend
• protobuf_grpc_backend - Macro for creating gRPC backends from protobuf definitions

Features

• enable_stop_iteration - Enables StopIterationMode for handling paused requests

Structs

TraceBackend

A Backend that stores the incoming requests to be later retrieved by the test. Delegates the response generation to the function provided in the constructor. This classes uses the interior mutability pattern to allow the test to retrieve the requests.

UnitGrpcRequest

Represents a gRPC request in unit tests.

UnitGrpcResponse

Represents a gRPC response in unit tests.

UnitHttpRequest

An HTTP request used in pdk-unit tests.

UnitHttpResponse

An HTTP response used in pdk-unit tests.

UnitLdapConfig

LDAP server configuration used to scope credential pairs registered with [UnitTest::add_ldap_data].

UnitTest

The main test orchestrator for running PDK policy unit tests.

UnitTestBuilder

A fluent builder for configuring and creating UnitTest instances.

UnitTestRequest

A handle to an in-flight request being processed by the policy.

Enums

StopIterationMode

Controls in which order how the test framework handles forwarding call responses and body processing when using the stop_iteration mode.

Traits

Backend

The interface for a backend that can be used to mock the response of an http service.

GrpcBackend

The interface for a backend that can be used to mock the response of a grpc service. For automatic implementation see protobuf_grpc_backend

UnitHttpMessage

Common read-only accessors for HTTP messages in unit tests.

Functions

dw2pel

Transform a DataWeave expression to PEL (Policy Expression Language) so it can be consumed by the PDK.

Attribute Macros

protobuf_grpc_backend

Attribute macro for implementing GrpcBackend on an impl block.