Skip to content

secondsky/claude-skills / plugins/better-auth/skills/better-auth

better-auth

Verified

Skill for integrating Better Auth - comprehensive TypeScript authentication framework for Cloudflare D1, Next.js, Nuxt, and 15+ frameworks. Use when adding auth, encountering D1 adapter errors, or implementing OAuth/2FA/RBAC features.

FileKindSize
SKILL.mdskill md29.2 KB
assets/auth-flow-diagram.mdmarkdown24.0 KB
references/advanced-features.mdmarkdown14.7 KB
references/cloudflare-worker-drizzle.tsscript12.7 KB
references/cloudflare-worker-kysely.tsscript9.7 KB
references/configuration-guide.mdmarkdown10.7 KB
references/database-schema.tsscript10.8 KB
references/databases/mongodb.mdmarkdown5.3 KB
references/databases/mysql.mdmarkdown6.8 KB
references/databases/postgresql.mdmarkdown8.4 KB
references/error-catalog.mdmarkdown12.9 KB
references/framework-comparison.mdmarkdown8.2 KB
references/frameworks/api-frameworks.mdmarkdown9.2 KB
references/frameworks/expo-mobile.mdmarkdown8.7 KB
references/frameworks/nextjs.mdmarkdown5.4 KB
references/frameworks/nuxt.mdmarkdown6.0 KB
references/frameworks/remix.mdmarkdown6.1 KB
references/frameworks/sveltekit.mdmarkdown6.3 KB
references/integrations/electron.mdmarkdown8.2 KB
references/migration-guide-1.4.0.mdmarkdown23.2 KB
references/migration-guide-1.5.0.mdmarkdown6.3 KB
references/nextjs/README.mdmarkdown1.1 KB
references/nextjs/postgres-example.tsscript4.0 KB
references/plugins/api-tokens.mdmarkdown10.0 KB
references/plugins/authentication.mdmarkdown9.2 KB
references/plugins/enterprise.mdmarkdown9.1 KB
references/plugins/payments.mdmarkdown8.0 KB
references/plugins/sso.mdmarkdown9.4 KB
references/plugins/test-utils.mdmarkdown5.5 KB
references/react-client-hooks.tsxother12.8 KB
references/setup-guide.mdmarkdown8.9 KB
references/v1.4-features.mdmarkdown8.2 KB
references/v1.5-features.mdmarkdown11.0 KB
references/v1.6-features.mdmarkdown6.1 KB
scripts/generate-secret.shexecutablescript2.0 KB
scripts/setup-d1-drizzle.shexecutablescript10.2 KB
scripts/test-auth-health.shexecutablescript2.1 KB
scripts/validate-config.tsscript4.3 KB

references/plugins/test-utils.md

View on GitHub
# better-auth Test Utilities Plugin

Testing helpers for integration and E2E testing. Do not use in production.

---

## Setup

### Server Plugin

```typescript
import { testUtils } from "better-auth/plugins";

export const auth = betterAuth({
    plugins: [testUtils({ captureOTP: true })],
});
```

### Access Test Helpers

```typescript
const ctx = await auth.$context;
const test = ctx.test;
```

---

## Factories

Create objects without persisting to database.

### createUser

```typescript
// With defaults
const user = test.createUser();
// { id: "...", email: "user-xxx@example.com", name: "Test User", emailVerified: true }

// With overrides
const user = test.createUser({
    email: "alice@example.com",
    name: "Alice",
    emailVerified: false,
});
```

### createOrganization

Requires organization plugin.

```typescript
const org = test.createOrganization({
    name: "Acme Corp",
    slug: "acme-corp",
});
```

---

## Database Helpers

Persist and remove test data.

### saveUser / deleteUser

```typescript
const user = test.createUser({ email: "test@example.com" });
const savedUser = await test.saveUser(user);

await test.deleteUser(user.id);
```

### saveOrganization / deleteOrganization

Requires organization plugin.

```typescript
const org = test.createOrganization({ name: "Test Org" });
const savedOrg = await test.saveOrganization(org);

await test.deleteOrganization(org.id);
```

### addMember

```typescript
const member = await test.addMember({
    userId: user.id,
    organizationId: org.id,
    role: "admin",
});
```

---

## Auth Helpers

Create authenticated sessions for testing protected routes.

### login

Creates a session and returns all auth data:

```typescript
const { session, user, headers, cookies, token } = await test.login({
    userId: user.id,
});
```

- `session` - Session object with userId, token, etc.
- `user` - User object
- `headers` - Headers with session cookie (for fetch/Request)
- `cookies` - Cookie array (for Playwright/Puppeteer)
- `token` - Session token string

### getAuthHeaders

```typescript
const headers = await test.getAuthHeaders({ userId: user.id });
const session = await auth.api.getSession({ headers });
const response = await fetch("/api/protected", { headers });
```

### getCookies

Browser testing tool compatible (Playwright, Puppeteer):

```typescript
const cookies = await test.getCookies({
    userId: user.id,
    domain: "localhost",
});

// Playwright
await context.addCookies(cookies);

// Puppeteer
for (const cookie of cookies) {
    await page.setCookie(cookie);
}
```

Each cookie: `name`, `value`, `domain`, `path`, `httpOnly`, `secure`, `sameSite`.

---

## OTP Capture

Passively captures OTPs as they are created. Does not prevent normal sending.

```typescript
export const auth = betterAuth({
    plugins: [
        testUtils({ captureOTP: true }),
        emailOTP({
            async sendVerificationOTP({ email, otp }) {
                // Normal sending still works
            },
        }),
    ],
});
```

### getOTP

```typescript
await auth.api.sendVerificationOTP({
    body: { email: "user@example.com", type: "sign-in" },
});

const otp = test.getOTP("user@example.com");
// "123456"
```

### clearOTPs

```typescript
test.clearOTPs();
```

---

## Integration Test Example (Vitest)

```typescript
import { describe, it, expect, beforeAll } from "vitest";
import { auth } from "./auth";
import type { TestHelpers } from "better-auth/plugins";

describe("protected route", () => {
    let test: TestHelpers;

    beforeAll(async () => {
        const ctx = await auth.$context;
        test = ctx.test;
    });

    it("should return user data for authenticated request", async () => {
        const user = test.createUser({ email: "test@example.com" });
        await test.saveUser(user);

        const headers = await test.getAuthHeaders({ userId: user.id });
        const session = await auth.api.getSession({ headers });
        expect(session?.user.id).toBe(user.id);

        await test.deleteUser(user.id);
    });
});
```

---

## E2E Test Example (Playwright)

```typescript
import { test, expect } from "@playwright/test";
import { auth } from "./auth";

test("dashboard shows user name", async ({ context, page }) => {
    const ctx = await auth.$context;
    const testUtils = ctx.test;

    const user = testUtils.createUser({
        email: "e2e@example.com",
        name: "E2E User",
    });
    await testUtils.saveUser(user);

    const cookies = await testUtils.getCookies({
        userId: user.id,
        domain: "localhost",
    });
    await context.addCookies(cookies);

    await page.goto("/dashboard");
    await expect(page.getByText("E2E User")).toBeVisible();

    await testUtils.deleteUser(user.id);
});
```

---

## OTP Verification Test Example

```typescript
describe("OTP verification", () => {
    let test: TestHelpers;

    beforeAll(async () => {
        const ctx = await auth.$context;
        test = ctx.test;
    });

    beforeEach(() => {
        test.clearOTPs();
    });

    it("should verify email with captured OTP", async () => {
        const email = "otp-test@example.com";
        const user = test.createUser({ email, emailVerified: false });
        await test.saveUser(user);

        await auth.api.sendVerificationOTP({
            body: { email, type: "email-verification" },
        });

        const otp = test.getOTP(email);
        expect(otp).toBeDefined();

        await auth.api.verifyEmail({
            body: { email, otp },
        });

        await test.deleteUser(user.id);
    });
});
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall