# 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.

### Login and consent

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.

| Address | Providers | What it does (login and consent) |
| --- | --- | --- |
| [`you+personal@example.com`](/docs/failure-testing/personal) | Microsoft | A 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.com`](/docs/failure-testing/guest) | Microsoft | An 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.com`](/docs/failure-testing/outsider) | Microsoft | Not a member or guest of the app’s tenant: a single-tenant app refuses the sign-in with AADSTS50020. |
| [`you+blocked@example.com`](/docs/failure-testing/blocked) | Google, Microsoft | After 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](/blog/better-auth-invalid-code) 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](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2). 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.

| Address | Providers | What it does (code exchange) |
| --- | --- | --- |
| [`you+badcode@example.com`](/docs/failure-testing/badcode) | Google, Microsoft, GitHub, Apple, Discord, LinkedIn, X, Facebook | The authorization code exchange returns invalid_grant. |
| [`you+down@example.com`](/docs/failure-testing/down) | Google, Microsoft, GitHub, Apple, Discord, LinkedIn, X, Facebook | The token endpoint returns 503 Service Unavailable. |
| [`you+flaky@example.com`](/docs/failure-testing/flaky) | Google, Microsoft, GitHub, Apple, Discord, LinkedIn, X, Facebook | The first exchange of each code returns 503; retrying with the same code succeeds. |
| [`you+slow@example.com`](/docs/failure-testing/slow) | Google, Microsoft, GitHub, Apple, Discord, LinkedIn, X, Facebook | The token endpoint responds only after a delay (10 seconds by default). |

What auth libraries do with these failures:

- [Better Auth invalid_code: test Google sign-in failures with Playwright](https://mockatoo.globalunderdog.com/blog/better-auth-invalid-code)

### 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.

| Address | Providers | What it does (refresh) |
| --- | --- | --- |
| [`you+returning@example.com`](/docs/failure-testing/returning) | Google, Apple | A 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.com`](/docs/failure-testing/revoked) | Google, Microsoft, GitHub, Apple, Discord, X | Sign-in works, but every refresh returns invalid_grant, as if access was revoked. |
| [`you+mfa@example.com`](/docs/failure-testing/mfa) | Microsoft | Sign-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.com`](/docs/failure-testing/throttled) | Microsoft | Sign-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.

| Address | Providers | What it does (profile data) |
| --- | --- | --- |
| [`you+hd@example.com`](/docs/failure-testing/hd) | Google | A Workspace user. The ID token includes hd with the email's domain. |
| [`you+unverified@example.com`](/docs/failure-testing/unverified) | Google, GitHub, Discord, LinkedIn | The email is reported as unverified (email_verified: false). |
| [`you+renamed@example.com`](/docs/failure-testing/renamed) | Google, Microsoft, GitHub, Apple, Discord, LinkedIn, X, Facebook | Same subject (sub) as the address without +renamed, but a different email, as if the user changed it. |
| [`you+noname@example.com`](/docs/failure-testing/noname) | Google, Microsoft, GitHub, Discord | No name, given_name, or family_name claims. |
| [`you+hidden@example.com`](/docs/failure-testing/hidden) | Apple | Hide My Email: the app gets a stable @privaterelay.appleid.com address with is_private_email: true. |
| [`you+strings@example.com`](/docs/failure-testing/strings) | Apple | email_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.com`](/docs/failure-testing/private) | GitHub | The email is private: /user returns email: null, so the app must read /user/emails (which needs the user:email scope). |
| [`you+noemail@example.com`](/docs/failure-testing/noemail) | Microsoft, Discord, LinkedIn, X, Facebook | No email claim, like an account without a mailbox. preferred_username still holds the sign-in name. |
| [`you+nophoto@example.com`](/docs/failure-testing/nophoto) | LinkedIn, Facebook | No picture claim in the ID token or /v2/userinfo, like a member without a profile photo. |
| [`you+firstname@example.com`](/docs/failure-testing/firstname) | Google | Only 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`:

```ts
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`](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/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](/docs/ci) describes. Give parallel workers distinct tagged addresses. The [Playwright](/docs/playwright), [Cypress](/docs/cypress) and [Selenium](/docs/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](https://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](/docs/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.
