Session tasks
A user signs in or signs up on an instance that requires more setup and is stopped on a session task before the session becomes active. Finishing the task activates the session.
Sub-features
setup-mfastops on the set-up-MFA task on an instance that requires MFA.complete-setup-mfaenrolls an authenticator app with a code and activates the session.sign-up-setup-mfaends a sign-up on the set-up-MFA task, with no second sign-in, and finishes it with an authenticator code.choose-organizationstops on the create-or-choose-organization task on an instance that forces an organization.setup-mfa-sms-onlyturns MFA on and the authenticator app off while the app runs, relaunches, and ends a sign-up on the set-up-MFA task with only SMS.
How to get to it (user POV)
- Sign in on an MFA-required app: the "set up two-step verification" screen appears.
- Sign up on an MFA-required app: the same screen appears after the email code.
- On that screen tap
Authenticator application, add the key to an authenticator, tapContinue, and type the code the authenticator shows. - Sign in on an app that requires an organization, as a user with no organization to choose: the "Create organization" screen appears.
Driving it with verify
Preconditions:
The first line of
setup-mfa,complete-setup-mfa, andsign-up-setup-mfaishost.useSettings({ config: { 'auth_multi_factor.required_for_sign_up': true }, environment: { 'user_settings.sign_up.mfa.required': true } }).The first line of
choose-organizationishost.useSettings({ config: { 'organization_settings.force_organization_selection': true }, environment: { 'organization_settings.force_organization_selection': true } }).The CLI puts the changed leaves back when each test ends.
.claude/skills/verify-clerk-android/references/instances.mddescribeshost.useSettings.Each spec except
sign-up-setup-mfaandsetup-mfa-sms-onlyseeds a user and launches with a sign-in ticket for that user. The session stays pending, so the home showsSigned out, and the launch names that withlandsOn: host.app.signedOut. The spec then tapse2e.auth.signInFullScreen, and AuthView adopts the pending session and shows the task.sign-up-setup-mfaandsetup-mfa-sms-onlyseed nobody. Each gets an email fromhost.newEmail()and signs up through the form.Setup MFA. Run
e2e-tests/bin/control-clerk-android run session-tasks/setup-mfa. After the tap AuthView showsclerk.auth.sessionTask.setupMfa.authenticatorApp, and the spec expectsclerk.auth.sessionTask.setupMfa.smsCodebeside it. Screenshotsession-task. It then taps the avatar at the top of the task view and expects the seeded user's email in the account sheet. Screenshotsession-task-account.Complete MFA setup. Run
e2e-tests/bin/control-clerk-android run session-tasks/complete-setup-mfa. It reaches the task the same way and takes screenshotsession-task-before-totp. It tapsclerk.auth.sessionTask.setupMfa.authenticatorApp, reads the key from theAdd authenticator applicationscreen, takes screenshottotp-secret, and tapsContinue. It expectsVerify authenticator appand fills the code field with the code thattotpinspecs/totp.tscomputes from the key. It expectsBackup codesand ten codes, takes screenshotbackup-codes, tapsClose, and waits for the home to showSigned in asthe seeded user's email with that user's ID. Screenshottask-complete.Sign up into the task. Run
e2e-tests/bin/control-clerk-android run session-tasks/sign-up-setup-mfa. It launches withauthMode: 'signUp', tapse2e.auth.signInFullScreen, signs up with the email, a run password, andCLERK_TEST_CODE, and expectsclerk.auth.sessionTask.setupMfa.authenticatorAppandclerk.auth.sessionTask.setupMfa.smsCodewith no further step. Screenshotsign-up-session-task. It then enrolls an authenticator app the same way, without thetotp-secretandbackup-codesscreenshots or the count of codes, closes the backup codes, and waits for the home to showSigned in asthe new email with a user ID. Screenshotsign-up-task-complete.SMS only. Run
e2e-tests/bin/control-clerk-android run session-tasks/setup-mfa-sms-only. It launches withauthMode: 'signUp', callshost.useSettingswith the config leaves'auth_multi_factor.required_for_sign_up': trueand'auth_multi_factor.authenticator_app.enabled': false, waits until the public environment shows'user_settings.sign_up.mfa.required': trueand'user_settings.attributes.authenticator_app.enabled': false, and launches again, because the SDK keeps the environment it read at launch. It signs up through the form assign-up-setup-mfadoes, expectsclerk.auth.sessionTask.setupMfa.smsCode, and expects noclerk.auth.sessionTask.setupMfa.authenticatorApp. Screenshotsms-only-session-task. The CLI puts both config leaves back when the test ends, sosetup-mfa, which runs next, sees the authenticator app again.Choose organization. Run
e2e-tests/bin/control-clerk-android run session-tasks/choose-organization. After the tap AuthView shows the organization form fieldclerk.organization.profileForm.name. Screenshotchoose-organization-task. The spec then taps the task view's UserButton,clerk.userButton.profile, and expects the seeded user's email in the account sheet. Screenshotchoose-organization-task-account.Proof. All five specs pass. The screenshots show each task screen, the account sheet names the user whose session is pending, and the home names the user whose task is finished.
Gotchas
- A task view is the proof that the session is pending. AuthView shows one only for a pending session, and the home shows
Signed in asonly for an active one. - The home treats a pending session as signed out and does not present the task by itself. Pass
landsOn: host.app.signedOutto the launch, then open AuthView from the home. - The avatar of the setup-MFA task view has no test tag. The spec finds it by its label,
User avatar, and taps it withhost.tap(middleOf(...)). The organization task view has a UserButton with the tagclerk.userButton.profile. The two account sheets differ: the first saysLog outand the secondSign out. - The authenticator screens have no test tags. The spec finds the key with
screen.getByText(/^[A-Z2-7]{16,}$/), which matches the one text on the screen that is a base32 key and nothing else. The line under it is the same key inside anotpauth://address, and the pattern does not match that.Continueand the titleVerify authenticator appare found by text, and the code field is the onlytextboxon its screen. - The spec computes the code as an authenticator does, from the key and the clock of the machine that runs it (RFC 6238, SHA-1, six digits, a 30 second step). A failure right at a 30 second boundary can be a clock edge, so rerun once before you debug.
- The backup codes show once Clerk accepts the code, and the task stays up until they are closed. The session is already active at Clerk by then, so the home is the proof that the task view has finished, not that the session changed. The backup codes screen has no tag and no
Continuebutton. Its title is stillAdd authenticator application, andBackup codesis the label over the codes. Find it by the textBackup codes, and close it withhost.tap(middleOf(screen.getByLabel('Close'))). - When the real on-screen keyboard is up, it covers the
clerk.organization.profileForm.submitbutton of the organization task form. agent-device's own input method draws no keyboard, so a normal run reaches the button.