Module testing 

Available on crate feature testing only.

Test helpers for applications that authenticate with Clerk through this crate.

Tokens are minted locally from an RSA key this crate generates, so tests exercise the real ClerkAuthLayer verification path with no Clerk instance, no network, and no JWKS mock.

Testing your application

When authentication is not the subject of the test — you just need a signed-in user so you can test what your app does — TestClerk is the whole API:

use dioxus_clerk::testing::TestClerk;

let clerk = TestClerk::new()?;

let layer = clerk.layer()?;              // wire into your router
let cookie = clerk.cookie("user_2abc")?; // send with a request

Testing authentication itself

When the auth behaviour is the subject — org permissions, expiry, tokens that should be rejected — TestSession builds the claims and TestIssuer signs them:

use dioxus_clerk::server::{ClerkAuthLayer, ClerkAuthLayerConfig};
use dioxus_clerk::testing::{TestIssuer, TestSession};

let issuer = TestIssuer::generate()?;

// The layer verifies against the issuer's keys; nothing is fetched.
let config = ClerkAuthLayerConfig::new("").with_static_jwks(issuer.jwks_json()?);
let layer = ClerkAuthLayer::from_config(config)?;

let admin = issuer.sign(
    &TestSession::new("user_2abc")
        .with_organization("org_2ghi")
        .with_organization_role("org:admin"),
)?;
let expired = issuer.sign(&TestSession::new("user_2abc").expired())?;

For the full setup — sharing a key with a browser test runner, SSR tests that need no token, and Playwright configuration including the window.Clerk fake that keeps a browser suite offline — see the testing guide.

Choosing a key

This crate deliberately ships no key material. Pick whichever fits:

• TestIssuer::generate — a fresh keypair, nothing on disk. Best when the tokens and the verifier live in the same process.
• TestIssuer::from_pem_file — load a key you generated ahead of time. Needed when something outside the test process (a browser test runner, a separately spawned server) must sign or verify with the same key.
• TestIssuer::from_pem_file_or_generate — load it, or create it on first use. Lets a gitignored key work on a fresh checkout with no setup step.

Note that RSA-2048 key generation takes on the order of 100ms and is variable, which is fine per suite but adds up per test. Generate once and share it:

use std::sync::LazyLock;
use dioxus_clerk::testing::TestIssuer;

static ISSUER: LazyLock<TestIssuer> =
    LazyLock::new(|| TestIssuer::generate().expect("test issuer"));

Do not ship this

Everything here mints tokens that a correctly configured verifier accepts. Keep the testing feature under [dev-dependencies], and never point a production ClerkAuthLayer at a jwks_json from this module.

Structs

TestClerk

A ready-made Clerk setup for tests that are about the application rather than about authentication.

TestIssuer

Mints Clerk-shaped session tokens signed by a local RSA key, and emits the matching JWKS for with_static_jwks.

TestSession

A Clerk session to mint a token for.

Enums

TestIssuerError

Something went wrong minting a test token or loading a test key.