Test Utils

Better Auth Ruby does not expose a public test_utils plugin yet. The upstream @better-auth/test-utils package is a TypeScript package, and there is no matching Ruby package in packages/.

Ruby tests should use the auth object, direct auth.api calls, and the internal adapter in test setup. That covers the same practical needs without documenting a plugin API that does not exist yet.

Integration Test Pattern

test/auth_flow_test.rb
require "test_helper"

class AuthFlowTest < Minitest::Test
  def setup
    @auth = BetterAuth.auth(
      secret: "test-secret",
      base_url: "http://localhost:3000",
      database: BetterAuth::Adapters::Memory.new,
      email_and_password: { enabled: true }
    )
  end

  def test_signed_in_user_can_fetch_session
    result = @auth.api.sign_up_email(
      body: {
        email: "user@example.com",
        password: "password123",
        name: "Test User"
      }
    )

    cookie = result.fetch(:headers).fetch("set-cookie")
    session = @auth.api.get_session(headers: { "cookie" => cookie })

    assert_equal "user@example.com", session.fetch(:user).fetch("email")
  end
end

Creating Records Directly

Use the internal adapter when the test needs setup data without walking through a public auth route.

test/admin_test.rb
user = auth.context.internal_adapter.create_user(
  email: "admin@example.com",
  name: "Admin",
  emailVerified: true
)

session = BetterAuth::Session.create(auth.context, user)
cookie = session.fetch(:headers).fetch("set-cookie")

Testing Protected Routes

For Rack apps, pass the session cookie into the request environment.

test/protected_route_test.rb
request = Rack::MockRequest.new(app)
response = request.get(
  "/dashboard",
  "HTTP_COOKIE" => cookie
)

assert_equal 200, response.status

OTP And Email Flows

Do not mock Better Auth internals unless the real dependency is impractical. Prefer configuring the plugin callback to capture values in the test.

test/email_otp_test.rb
sent_codes = {}

auth = BetterAuth.auth(
  secret: "test-secret",
  base_url: "http://localhost:3000",
  database: BetterAuth::Adapters::Memory.new,
  plugins: [
    BetterAuth::Plugins.email_otp(
      send_verification_otp: ->(data, _request) {
        sent_codes[data.fetch(:email)] = data.fetch(:otp)
      }
    )
  ]
)

auth.api.send_verification_otp(
  body: { email: "user@example.com", type: "sign-in" }
)

otp = sent_codes.fetch("user@example.com")

What Is Not Available Yet

  • No public BetterAuth::Plugins.test_utils plugin.
  • No ctx.test helper surface.
  • No browser cookie helper for Playwright or Puppeteer.
  • No Ruby package equivalent to upstream @better-auth/test-utils.

If a Ruby test-utils package is added later, this page should be rewritten around that public API.

Edit on GitHub

Previous Page

JWT

Next Page

Stripe

On this page