If you're developing a custom plugin for Better-Auth, you may need to test it. This library is intended to provide utilities to help you test your plugins.

npm install @better-auth-kit/tests

import { getTestInstance } from "@better-auth-kit/tests";
import { describe, expect, it, vi } from "vitest";
import { myPlugin, myClientPlugin } from "./my-plugin.ts";
 
const { auth, db, client, testUser, signInWithTestUser } = await getTestInstance(
	{
		plugins: [myPlugin()],
	},
	{
		clientOptions: {
			plugins: [myClientPlugin()],
		},
	},
);
 
 
// Your test user is already created
const { headers, user } = await signInWithTestUser();
 
describe("My Plugin", () => {
	it("should do something cool", async () => {
		const result = await client.myPlugin.doSomethingCool();
        
		expect(result).toBe(true);
	});
});

API

getTestInstance

Optionally takes two arguments, the first is the options for the betterAuth instance, the second is the options for the test instance itself.

You can configure the betterAuth client instance inside the second argument.

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

Options

• 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.
• testWith - The database to use for the test instance. (sqlite, postgres, mongodb, mysql)

Methods

• auth - The Better-Auth instance.
• client - The Better-Auth client instance.
• testUser - 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.

auth

The Better-Auth instance.

client

The Better-Auth client instance.

testUser

The premade test user.

signInWithTestUser

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

signInWithUser

const { headers, user } = 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,
    },
});

db

The database adapter.

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