pdk_unit/lib.rs
1// Copyright (c) 2026, Salesforce, Inc.,
2// All rights reserved.
3// For full license text, see the LICENSE.txt file
4
5//! # pdk-unit
6//!
7//! A unit testing framework for PDK (Policy Development Kit) policies that enables testing
8//! Flex Gateway policies without requiring a running Envoy proxy or WebAssembly runtime.
9//!
10//! ## Overview
11//!
12//! `pdk-unit` provides a complete in-process testing solution for PDK policies by stubbing
13//! the Proxy-Wasm host environment. This allows developers to write fast, deterministic
14//! unit tests that verify policy behavior without the overhead of integration testing.
15//!
16//! ## Quick Start
17//!
18//! ```ignore
19//! use pdk_unit::{UnitHttpRequest, UnitHttpResponse, UnitHttpMessage, UnitTestBuilder};
20//!
21//! #[test]
22//! fn test_my_policy() {
23//! let mut tester = UnitTestBuilder::default()
24//! .with_config(r#"{"key": "value"}"#)
25//! .with_entrypoint(crate::configure);
26//!
27//! let request = UnitHttpRequest::get()
28//! .with_header(":path", "/api/test");
29//!
30//! let response = tester.request(request);
31//!
32//! assert_eq!(response.status_code(), 200);
33//! }
34//! ```
35//!
36//! ## Core Components
37//!
38//! - [`UnitTestBuilder`] - Fluent builder for configuring test instances
39//! - [`UnitTest`] - Main test orchestrator managing request lifecycles
40//! - [`UnitTestRequest`] - Handle to an in-flight request being processed
41//! - [`UnitHttpRequest`] - HTTP request with method constructors (e.g. [`UnitHttpRequest::get`])
42//! - [`UnitHttpResponse`] - HTTP response with a [`status_code`](UnitHttpResponse::status_code) accessor
43//! - [`UnitHttpMessage`] - Trait providing common read accessors for both request and response
44//!
45//! ## Backends
46//!
47//! Mock upstream services using the [`Backend`] and [`GrpcBackend`] traits:
48//!
49//! - [`TraceBackend`] - Records all incoming requests for later inspection; also acts as a configurable response backend
50//! - [`protobuf_grpc_backend`] - Macro for creating gRPC backends from protobuf definitions
51//!
52//! ## Features
53//!
54//! - `enable_stop_iteration` - Enables [`StopIterationMode`] for handling paused requests
55
56mod backends;
57mod dw;
58mod host;
59mod tester;
60
61pub use crate::tester::builder::UnitTestBuilder;
62pub use crate::tester::io::{
63 UnitGrpcRequest, UnitGrpcResponse, UnitHttpMessage, UnitHttpRequest, UnitHttpResponse,
64};
65pub use crate::tester::unit_test::{StopIterationMode, UnitTest, UnitTestRequest};
66pub use backends::{ldap::UnitLdapConfig, trace::TraceBackend, Backend, GrpcBackend};
67pub use dw::dw2pel;
68pub use pdk_unit_macros::protobuf_grpc_backend;