Test Utils

This library comes with test utilities to assist you in writing code to test your Better-Auth plugins.

Installation

npm install @better-auth-extended/test-utils

Usage

import { betterAuth } from "better-auth";
import { getTestInstance } from "@better-auth-extended/test-utils";
import { myPlugin, myPluginClient } from "./my-plugin";

const { auth, db, client, testUser, signUpWithTestUser } =
    await getTestInstance({
        options: {
            database: new Database(), // Your database adapter
            plugins: [myPlugin()],
        },
        clientOptions: {
            plugins: [myPluginClient()],
        },
    });

or

import { betterAuth } from "better-auth";
import { getTestInstance } from "@better-auth-extended/test-utils";
import { myPlugin, myPluginClient } from "./my-plugin";

const auth = betterAuth({
    database: new Database(), // Your database adapter
    plugins: [myPlugin()],
    secret: "better-auth.secret",
    emailAndPassword: {
        enabled: true,
        autoSignIn: true,
    },
    rateLimit: {
        enabled: false,
    },
    advanced: {
        disableCSRFCheck: true,
        cookies: {},
    },
});

const { db, client, testUser, signUpWithTestUser } = await getTestInstance({
    auth,
    clientOptions: {
        plugins: [myPluginClient()],
    },
});

Writing Tests

You can now use the test APIs to test your plugin:

const { headers, user } = await signUpWithTestUser();

describe("My Plugin", () => {
    it("should do something cool", async () => {
        const result = await client.myPlugin.doSomethingCool();

        expect(result).toBe(true);
    });
});

Then run the tests, for example, using Vitest:

vitest foobar

API

getTestInstance

Optionally takes a single config object with options for the betterAuth instance and test instance configuration.

You can configure the betterAuth client instance inside the config object.

const {
    auth,
    db,
    client,
    testUser,
    signUpWithTestUser,
    signInWithTestUser,
    signInWithUser,
    cookieSetter,
    customFetchImpl,
    sessionSetter,
    context,
    resetDatabase,
} = await getTestInstance({
    options: {
        // Better-Auth options
        plugins: [myPlugin()],
    },
    clientOptions: {
        // Client options
        plugins: [myPluginClient()],
    },
});

Options

• options - The options for the Better-Auth instance.
• auth - An existing Better-Auth instance to use instead of creating a new one.
• clientOptions - The options for the Better-Auth client instance.
• port - The baseURL port for the better-auth instance.
• disableTestUser - Whether to disable the test user.
• testUser - The test user to use for the test instance.
• shouldRunMigrations - Whether to run database migrations on initialization.

Methods

• auth - The Better-Auth server instance.
• client - The Better-Auth client instance.
• signUpWithTestUser - Sign up with the premade test user.
• signInWithTestUser - Sign in with the premade test user.
• signInWithUser - Sign in with a custom user.
• cookieSetter - Set the cookie for the test instance.
• customFetchImpl - The custom fetch implementation for the test instance.
• sessionSetter - Set the session for the test instance.
• resetDatabase - Reset the database by clearing all auth tables.

auth

The Better-Auth server instance.

client

The Better-Auth client instance.

testUser

The premade test user.

signUpWithTestUser

const { headers, user, session, token } = await signUpWithTestUser();

signInWithTestUser

const { headers, user, session, token } = await signInWithTestUser();

signInWithUser

const { headers, user, session, token } = await signInWithUser(email, password);

cookieSetter

Useful for getting the session of a successful sign in and applying that to a new headers object's cookie.

const headers = new Headers();
await client.signIn.email(
    {
        email: testUser.email,
        password: testUser.password,
    },
    {
        onSuccess: cookieSetter(headers),
    }
);

customFetchImpl

By default, when using the auth client, we make a fetch request to the better-auth server whenever you call an endpoint. However, you can optionally provide the customFetchImpl to bypass this and it will skip the fetch request to the better-auth server, and instead directly invoke the endpoint on the server.

const client = createAuthClient({
    baseURL: "http://localhost:3000",
    fetchOptions: {
        customFetchImpl,
    },
});

sessionSetter

Useful for getting the session from the response of a successful sign in and applying that to a new headers object.

const headers = new Headers();
await client.signIn.email(
    {
        email: testUser.email,
        password: testUser.password,
    },
    {
        onSuccess: sessionSetter(headers),
    }
);

const response = await client.listSessions({
    fetchOptions: {
        headers,
    },
});

context

The Better-Auth context object.

db

The database adapter.

await db.create({
    model: "sometable",
    data: {
        hello: "world",
    },
});

resetDatabase

Reset the database by clearing all auth tables.

// Reset all auth tables
await resetDatabase();

// Reset specific tables
await resetDatabase(["user", "session"]);