Suitable: You need to verify Magic Link login in your own Auth.js application or an environment you’re authorized to test. Use a controlled test inbox that lets you read the message and open its link: a successful send request alone does not prove that the email arrived or that login works.
Not suitable: You need to prove production-wide inbox placement, or you’re testing an account that must remain recoverable through a long-term personal mailbox.
This guide is for developers integrating the Auth.js Email Provider who need evidence that their application can send and process a login link.
It’s also for QA teams checking message contents, callback results, and failure cases.
If you maintain a preview environment, it helps you keep test mail out of personal and work inboxes.
Set the acceptance boundary before testing
Treat the flow as separate outcomes, not one “email sent” result:
| Stage | What to establish | Evidence to keep |
|---|---|---|
| Request | Your application accepted the login request and invoked its configured email flow | Test run identifier, account identifier, environment, and application log |
| Receipt | The expected message reached the controlled test inbox | The received message, recipient, and relevant headers or inbox record |
| Login | The link was processed and the application established the expected authenticated state | Callback result, visible account state, and a protected-resource check |
This distinction matters when a mail service accepts an outgoing request but the message never appears in the inbox. It also matters when the message arrives but its link points to another environment, or when a redirect occurs without a session being established.
Auth.js documents Magic Links as an email authentication method. Its Email Provider guide describes the email sign-in flow; the provider’s configuration and your project’s adapter behavior still need to be checked against the implementation you are testing. Review the Auth.js Email Provider guide and the Email Provider API reference rather than treating a particular project’s configuration as a universal default.
Before you start, choose the environment you intend to test: development, preview, or production. Record the expected destination after login and the account state you expect there. Keep the test within your own application or an environment you have permission to use.
A preview test can confirm that a particular preview configuration works. It cannot, on its own, establish that production uses the same mail settings, route, template, or delivery path.
Prepare the environment and inbox
Choose a test recipient that you can actually access. For a Magic Link, the inbox must let you read the email and open the complete link; an address that only confirms message arrival is not enough to test the callback. Avoid personal or shared work addresses if test messages could expose account details or create lasting noise. For a broader decision about disposable addresses and masked forwarding, see masked or disposable email.
Set up the test with the same project-specific conditions you want to accept. Note the environment, recipient, application build or release under test, and the expected post-login page. If you use a test mailbox, make sure you can associate the received message with this run rather than confusing it with an earlier message.
Auth.js configuration can depend on the selected provider and adapter. For example, the official Drizzle adapter guide explains that adapter’s setup, while the adapter API reference documents the adapter interface. Check the guide for the adapter your application actually uses; don’t infer its behavior from a different adapter or from a mail provider’s response.
| Configuration area | What to verify in your project | Why it affects acceptance |
|---|---|---|
| Environment | The application is using the intended development, preview, or production settings | A test can pass against the wrong environment and still fail where users sign in |
| Email provider | The project’s Email Provider options and verification request flow match the active implementation | Provider configuration determines how the application prepares and sends its login email |
| Adapter | The selected adapter and its configured storage behavior support the flow your application expects | A working outbound message does not establish that the rest of the sign-in flow can complete |
| Link construction | The email template or request handler points to the intended application and callback route | A valid-looking email can still send the user to the wrong environment |
| Expected state | The account and destination after sign-in are known before you click | This makes a redirect distinguishable from a successful authenticated session |
As a privacy measure, avoid using real personal information in test accounts unless you need it for an authorized test. Test mail and account records can persist in logs, inboxes, or adapter storage. The privacy guide offers additional context for separating test activity from personal email use.
Trigger and associate the login request
Start at your application’s own sign-in entry point. Enter the controlled test address, submit the request, and record enough context to connect the resulting message to this attempt. A run label, test account identifier, and environment name are useful even if your application does not support a dedicated correlation field.
Then check the application-side evidence. Confirm that the request was accepted and that your configured email flow was invoked. If you inspect logs, use the identifiers your own application already records; don’t add real credentials, full verification links, or unnecessary personal data to a shared log just to make the test easier to trace.
The provider API exposes configuration points such as sendVerificationRequest and generateVerificationToken; inspect the options and behavior used by your project in the Email Provider API reference. These are implementation details to verify, not proof of delivery. A successful invocation or a mail service’s acceptance response does not show that the test address received the email.
Keep the claims separate: “The request was accepted,” “the message appeared in the inbox,” and “the user signed in” are three different results. Record each only when you have evidence for that stage.
If the app reports a failure before sending, investigate the application’s provider and environment configuration first. If the app reports a successful request but the inbox is empty, investigate the path between the application and the receiving inbox. Don’t mark the login flow accepted just because the first stage passed.
Inspect the received message and destination
Once the email arrives, verify that it belongs to this test run. Check the recipient, the visible message content, and the destination encoded in the login link. If you can safely inspect message headers, keep them as supplementary evidence; they do not replace opening the link and verifying the session.
The destination should match the environment you selected before sending the request. If a preview test opens a production site, or a development email returns to an unrelated route, inspect the settings and code your project uses to construct the site URL, callback path, and email template. Auth.js installation and route setup can vary with the project, so compare your setup with the official installation and route guidance rather than assuming a fixed deployment route.
| Observed result | What it establishes | What to investigate next |
|---|---|---|
| No message in the controlled inbox | Receipt has not been demonstrated | Check application logs, sending-service response, recipient spelling, and the receiving inbox’s filtering |
| Message arrives at the wrong address | The test recipient or message addressing is incorrect | Compare the submitted address with the recipient shown on the received message |
| Link targets the wrong environment | The message arrived, but the link destination is not accepted | Review the active environment settings, route configuration, and link construction in the template |
| Link opens the expected application | The destination is plausible | Continue to callback and authenticated-state checks; arrival and a plausible URL are not login proof |
Don’t copy a full login link into general chat, an issue tracker, or a long-lived test report. Treat it as a sensitive, short-lived authentication artifact, even if the application’s exact link lifetime and reuse behavior are not yet known.
Open the link and verify the session
Open the message link in the environment you intend to test. Follow the complete redirect flow and note whether the callback finishes, whether the user reaches the expected page, and whether the application recognizes the expected account as signed in.
A page transition is not enough. Check a protected resource or another application-controlled signal that requires an authenticated session. Auth.js’s resource protection guide describes approaches for protecting application resources; use the protection method your application actually uses as part of the acceptance evidence.
Keep callback handling and session establishment separate in your test record:
- Callback: Did the link reach the intended application route, and did the application handle the sign-in attempt without an error?
- Account: Is the displayed or otherwise verified account the one associated with the test request?
- Session: Does the application recognize the user as authenticated when accessing a protected area?
- Destination: Did the signed-in user reach the expected page for this environment?
If the browser shows a success screen but a protected area still treats the user as signed out, the end-to-end login has not passed. If the callback fails, preserve the relevant error and environment details, but redact the full link and any token-like values before sharing the report.
Re-request, replay, and close the evidence gap
Repeat the test in your authorized environment with cases that reveal how your own application handles edge conditions. Request a new message, then test the original link again if your test design permits it. Also check how the application responds to a link it considers invalid. Record what actually happens instead of asserting a universal outcome.
The Email Provider and adapter configuration are part of your application’s behavior. Don’t assume every Auth.js implementation has the same token lifetime, old-link invalidation rule, or user-facing error. Check the settings and code in your project, then compare the observed behavior with the acceptance criteria your team set.
Use this sign-off list to decide whether the test has enough evidence:
- [ ] I recorded the application environment and the test account used.
- [ ] I confirmed that the sign-in request reached the configured email flow.
- [ ] I found the corresponding message in a controlled test inbox.
- [ ] I checked the recipient and confirmed that the link targets the intended environment.
- [ ] I opened the link and verified the expected account and authenticated session.
- [ ] I checked the protected-resource behavior, rather than relying only on a redirect.
- [ ] I recorded the actual results for a new request, repeated use, and an invalid-link case, where those cases are in scope.
- [ ] I kept send, receipt, callback, and session evidence distinct in the test report.
- [ ] I stated what remains untested, including any separate production or target-inbox check.
For an automated test, apply the same boundaries: wait for the message using a test mechanism you control, identify the message for the current run, and assert the application’s authenticated state after following the link. Keep secrets out of reports and make cleanup consistent with your project’s data-retention needs. The automation should not treat a mail service’s accepted request as a received email or a successful session.
FAQ
How can I tell whether a test address actually received an Auth.js Magic Link email?
Check the controlled test inbox for the specific message, then match its recipient and contents to the login request you recorded. A successful send request or provider response only confirms that the request progressed through that part of the sending path; it does not prove inbox delivery. Keep the received message as separate evidence from the application log.
How do I confirm that opening the email link really signed the user in?
Follow the link in the intended test environment and verify the resulting authenticated state, not just a redirect or success page. Check the application UI and the server-side or protected-resource behavior your project uses to recognize a session. Record callback handling and session establishment separately so a navigation event cannot stand in for proof of login.
What should I test when someone clicks a Magic Link more than once?
In your authorized test environment, check the first use, a later reuse of the same link, a newly requested link, and a link your project treats as invalid. Record the actual result and user-facing error. Auth.js behavior depends on your implementation and configuration, so do not assume a universal expiry period, invalidation rule, or error message.
Which settings should I inspect when a test email opens the wrong environment?
Compare the environment that initiated the request with the destination encoded in the email link. Then inspect your application’s site URL and callback or route configuration, plus the email template that constructs the link. Check the environment-specific settings your project actually uses; do not assume a fixed Auth.js default or change production settings to make a test pass.
For this workflow, the test recipient needs to do more than accept a message: you must be able to read the email, inspect its destination, and reopen or replace it during authorized checks. If your current test setup needs a separate inbox for those tasks, you can review TMPFox’s available receiving options from the TMPFox homepage. Use it only where its current capabilities fit your test; keep long-term, recoverable accounts and tests that require a persistent reply address on an appropriate mailbox.
Frequently asked questions
How can I tell whether a test address actually received an Auth.js Magic Link email?
Check the controlled test inbox for the specific message, then match its recipient and contents to the login request you recorded. A successful send request or provider response only confirms that the request progressed through that part of the sending path; it does not prove inbox delivery. Keep the received message as separate evidence from the application log.
How do I confirm that opening the email link really signed the user in?
Follow the link in the intended test environment and verify the resulting authenticated state, not just a redirect or success page. Check the application UI and the server-side or protected-resource behavior your project uses to recognize a session. Record callback handling and session establishment separately so a navigation event cannot stand in for proof of login.
What should I test when someone clicks a Magic Link more than once?
In your authorized test environment, check the first use, a later reuse of the same link, a newly requested link, and a link your project treats as invalid. Record the actual result and user-facing error. Auth.js behavior depends on your implementation and configuration, so do not assume a universal expiry period, invalidation rule, or error message.
Which settings should I inspect when a test email opens the wrong environment?
Compare the environment that initiated the request with the destination encoded in the email link. Then inspect your application's site URL and callback or route configuration, plus the email template that constructs the link. Check the environment-specific settings your project actually uses; do not assume a fixed Auth.js default or change production settings to make a test pass.