Testing your integration

Exercise your Rails app’s authentication flows using delivered links and a browser test authenticator.

Use helpers in your host tests

Install AddAuth through your app’s Gemfile and enable the features you test. These helpers are for application integration tests; gem contributor commands live in the public repository’s contributor guide.

require "add_auth/testing"

Open the intended delivered link

After your test requests a link and performs its queued jobs, select the email from Rails’ test deliveries. The helper returns a URI and requires exactly one matching token link:

mail = ActionMailer::Base.deliveries.last
uri = AddAuth::Testing.delivered_link(mail, purpose: :sign_in)
visit uri.request_uri

Allowed purposes are :sign_in, :reauthentication and :recovery. In your browser test, submit the displayed confirmation form and check the resulting account state. A GET alone must not consume the link. Do not print the URI or include live token links in screenshots.

Use a virtual authenticator

Add Selenium to your app’s test dependencies and use a driver that supports virtual authenticators. With a Selenium-backed Capybara session named browser:

AddAuth::Testing.with_virtual_authenticator(browser.driver.browser) do |_authenticator|
  browser.visit "/passkeys"
  # Complete the account's fresh verification and add-passkey flow.
  # Assert the new credential appears, then sign out and sign in with it.
end

The helper supplies a discoverable, user-verified CTAP2 test authenticator and removes it when the block exits, including on failure. This tests your app’s browser integration; it does not establish physical-device or phone/computer interoperability.

Cover your actual account lifecycle

• Sign in, revoke another session, and verify that browser’s next request is rejected.
• Use expired, consumed and wrong-browser email links.
• Check that a protected write is refused after proof expiry, password change or session revocation.
• Test passkey removal and recovery under both default and strict policy.
• Repeat permitted password/email navigation with JavaScript disabled and test your customized views with Turbo.

The helper methods do not depend on a particular assertion framework. Your host supplies its test runner, fixtures, mail/job setup and browser driver. Real deployment acceptance still includes your actual mailbox, queue, cache, captcha account and physical devices. Use the deployment checklist for that work.