OAuth failure testing: make sign-in fail on purpose

Your sign-in tests probably cover the happy path. The failure paths run only when a provider refuses the user, the token endpoint breaks or the profile comes back incomplete, and a provider rarely does any of that on cue. This page covers why those paths go untested, what each failure looks like, and how to reproduce it from a test.

Why sign-in failures go untested

You can't make Google fail on demand. A 503 from the token endpoint arrives when the provider sends it, so a test can't wait for one. Real providers also block the browsers that tests run in. They add bot checks and CAPTCHAs, ask for MFA and rate-limit repeated logins, so a test that signs in with a real account is fragile before it reaches the failure path.

Mockatoo is a hosted mock that copies the sign-in behavior of eight providers. It has no bot checks, and it allows bursts of sign-ins. A failure is a tag on the email address: you+down@example.com makes the token endpoint return 503 Service Unavailable. Each tagged address is a separate user with the same password, so a test picks its failure by picking its address.

The four steps where sign-in fails

Sign-in can fail at four steps. Each section below says what goes wrong and what the app should do. The table under each heading links the tags that reproduce the step and the error pages written for them.

The provider refuses the user, or the user refuses the provider. +blocked shows Google's "Access blocked" page, with admin_policy_enforced, and Microsoft's "Need admin approval" page in place of consent. The user never reaches Authorize, so there is no session. +outsider makes a single-tenant Microsoft app refuse the sign-in with AADSTS50020, and +personal refuses a personal Microsoft account when the app's tenant is organizations or a specific tenant. Clicking Deny is a different failure: the provider returns access_denied with the original state, as the real providers do.

A policy refusal won't change on retry. The app should keep the user signed out and say that the provider refused access, not ask them to try again.

AddressProvidersWhat it does (login and consent)
you+personal@example.comMicrosoftA personal Microsoft account (tid 9188040d-6c67-4c5b-b112-36a304b66dad). Refused when the app’s tenant is organizations or a specific tenant, unless also +guest.
you+guest@example.comMicrosoftAn invited guest when the app’s tenant is a specific tenant: tid and iss name that tenant, idp names the guest’s home tenant, and oid differs from the user’s own. Can be combined with personal.
you+outsider@example.comMicrosoftNot a member or guest of the app’s tenant: a single-tenant app refuses the sign-in with AADSTS50020.
you+blocked@example.comGoogle, MicrosoftAfter login, shows Google’s “Access blocked” page with admin_policy_enforced instead of consent.

Code exchange

After the provider redirects back with a code, the app's server exchanges it for tokens, and the exchange can fail four ways. +down returns 503 Service Unavailable. +flaky returns 503 once, then succeeds for the same code. +slow answers only after a delay, 10 seconds by default. +badcode returns invalid_grant, so the code is rejected.

Better Auth folds all of these into one error. Any failed exchange redirects to ?error=invalid_code, and the cause reaches only the server log. The Better Auth invalid_code post shows the log lines for a 503 and for a bad code, and both reach the browser the same way.

The app's message has to work for both causes. It should say that sign-in didn't finish and offer a fresh sign-in, rather than retrying the exchange: OAuth says a client must not use a code more than once. The example's +down test expects "Sign-in failed before it finished. Try again in a minute." and checks that the user is still signed out.

AddressProvidersWhat it does (code exchange)
you+badcode@example.comGoogle, Microsoft, GitHub, Apple, Discord, LinkedIn, X, FacebookThe authorization code exchange returns invalid_grant.
you+down@example.comGoogle, Microsoft, GitHub, Apple, Discord, LinkedIn, X, FacebookThe token endpoint returns 503 Service Unavailable.
you+flaky@example.comGoogle, Microsoft, GitHub, Apple, Discord, LinkedIn, X, FacebookThe first exchange of each code returns 503; retrying with the same code succeeds.
you+slow@example.comGoogle, Microsoft, GitHub, Apple, Discord, LinkedIn, X, FacebookThe token endpoint responds only after a delay (10 seconds by default).

What auth libraries do with these failures:

Refresh

The session worked, and the next refresh fails. +revoked makes every refresh return invalid_grant, as if access was revoked. X returns invalid_request and GitHub returns bad_refresh_token for the same case. +mfa makes Microsoft's refresh return invalid_grant with AADSTS50076 and a claims challenge, so the user has to sign in again. +throttled makes Microsoft return 429 Too Many Requests with a Retry-After header. +returning covers a returning user: Google sends no refresh token to a user who already consented, unless the app sends prompt=consent.

For a revoked grant or an MFA challenge, the app should end the session and send the user through sign-in again. For a 429, it should wait for the Retry-After delay before it tries again.

AddressProvidersWhat it does (refresh)
you+returning@example.comGoogle, AppleA user who already consented. Same subject and email as the address without +returning, and access_type=offline returns no refresh token unless the app sends prompt=consent.
you+revoked@example.comGoogle, Microsoft, GitHub, Apple, Discord, XSign-in works, but every refresh returns invalid_grant, as if access was revoked.
you+mfa@example.comMicrosoftSign-in works, but every refresh returns invalid_grant with AADSTS50076 and a claims challenge, as if a conditional access policy now requires MFA. The app must send the user to sign in again.
you+throttled@example.comMicrosoftSign-in works, but every refresh returns 429 Too Many Requests with a Retry-After header.

Profile data

Sign-in succeeds, but the profile isn't shaped the way the app assumes. +unverified sets email_verified to false, and on GitHub it marks the primary email unverified. +noemail leaves out the email altogether. +private makes GitHub's /user return email: null, so the app has to read /user/emails, which needs the user:email scope. +hidden gives an Apple Hide My Email address on privaterelay.appleid.com with is_private_email set to true. +noname removes the name claims for Google, and sets GitHub's name to null, as for a user who never set one.

An app that keys accounts on email has to handle a missing or unverified one. An app that shows the name has to fall back when it's absent. For GitHub's null name, apps usually fall back to the login.

AddressProvidersWhat it does (profile data)
you+hd@example.comGoogleA Workspace user. The ID token includes hd with the email's domain.
you+unverified@example.comGoogle, GitHub, Discord, LinkedInThe email is reported as unverified (email_verified: false).
you+renamed@example.comGoogle, Microsoft, GitHub, Apple, Discord, LinkedIn, X, FacebookSame subject (sub) as the address without +renamed, but a different email, as if the user changed it.
you+noname@example.comGoogle, Microsoft, GitHub, DiscordNo name, given_name, or family_name claims.
you+hidden@example.comAppleHide My Email: the app gets a stable @privaterelay.appleid.com address with is_private_email: true.
you+strings@example.comAppleemail_verified and is_private_email are the strings "true" and "false", which Apple sends instead of booleans for some users. is_private_email is "false" for a real address.
you+private@example.comGitHubThe email is private: /user returns email: null, so the app must read /user/emails (which needs the user:email scope).
you+noemail@example.comMicrosoft, Discord, LinkedIn, X, FacebookNo email claim, like an account without a mailbox. preferred_username still holds the sign-in name.
you+nophoto@example.comLinkedIn, FacebookNo picture claim in the ID token or /v2/userinfo, like a member without a profile photo.
you+firstname@example.comGoogleOnly a first name: name and given_name, no family_name.

How to test a failure

Give every test its own address. you+e2e-<uuid>.down@example.com is a separate user with your account's password, so there is nothing to seed or clean up. The Playwright guide's createAddress() helper appends a random tag for each test, so tests and parallel workers never share a user.

The Better Auth example has one spec per special tag. This is the one for +down:

import { expect, test } from "@playwright/test";const email = process.env.MOCKATOO_TEST_EMAIL ?? "";const password = process.env.MOCKATOO_TEST_PASSWORD ?? "";test("+down: tells the user to retry when sign-in cannot finish", async ({	page,}) => {	const address = email.replace("@", `+e2e-${crypto.randomUUID()}.down@`);	// A provider outage also becomes invalid_code in Better Auth. The app	// cannot distinguish it from a bad code, so it offers the same retry advice.	await page.goto("/");	await page.getByRole("button", { name: "Sign in with Google" }).click();	await page.getByLabel("Email", { exact: true }).fill(address);	await page.getByLabel("Password", { exact: true }).fill(password);	await page.getByRole("button", { name: "Log in with password" }).click();	await page.getByRole("button", { name: "Authorize" }).click();	await expect(page).toHaveURL(		(url) =>			url.pathname === "/" && url.searchParams.get("error") === "invalid_code",	);	await expect(		page.getByRole("alert").filter({			hasText: "Sign-in failed before it finished. Try again in a minute.",		}),	).toHaveText("Sign-in failed before it finished. Try again in a minute.");	await expect(		page.getByRole("button", { name: "Sign in with Google" }),	).toBeVisible();	await expect(page.getByText("You are logged in")).toBeHidden();});

The spec is down.spec.ts in the examples repository. It signs in as a fresh +down address, clicks Authorize, and checks three things: the browser returns to / with error=invalid_code, the alert asks the user to try again, and the sign-in button is back without a session. It reads the test account from MOCKATOO_TEST_EMAIL and MOCKATOO_TEST_PASSWORD, which the dashboard shows. Keep both in an ignored env file, not in the repository. The assertions check this example's wording, so change the alert text to match your app.

In CI, store the same two values as secrets and pass them to the test command, as the CI guide describes. Give parallel workers distinct tagged addresses. The Playwright, Cypress and Selenium guides each have a section on edge-case tags, with the same tags in their own runners.

What a mock can't test

Some failures never reach the mock. Mockatoo accepts any http or https callback and has one shared client, mockatoo / mockatoo-secret. So redirect_uri_mismatch can't happen, and neither can invalid_client. The shared client also hides a wrong production client secret, so check your real registration for those.

A state mismatch comes from your app's session setup, not from the provider, so no tag reproduces it. Test it in the session code.

Refresh tokens don't expire from age or inactivity, so a session left idle for months still refreshes here. Use +revoked to exercise expired or revoked grant handling instead. The mock's tokens are valid only at the mock, and it serves only the endpoints sign-in needs, so an app that calls the provider's API after sign-in can't test those calls against it.

Next step

Create a test account at app.mockatoo.globalunderdog.com/signup. The sign-up sends a magic link to your inbox, and the dashboard then shows your test email and password. Read email tags for the special addresses each provider supports. Start with you+down@example.com: +down applies to all eight providers, so it's the first failure to add.