Persistent Chrome profile
Provide your coding agent with a Chrome profile directory to preserve login state, cookies, bookmarks, extensions, and local storage between sessions. After you sign in manually once, later sessions that use the same profile start with the saved authentication state.
First time — create a profile and log in:
/shiplight verify https://app.example.com — use the Chrome profile
at ./my-chrome-profile. I'll log in manually.Complete the login process in the browser window. Chrome saves the session in the profile directory.
Subsequent sessions — your login is already there:
/shiplight verify https://app.example.com/dashboard —
use the Chrome profile at ./my-chrome-profileYou do not need to provide credentials or manage a separate storage state file on later runs. A persistent profile is useful for:
- Applications with Google OAuth or SSO — Complete the login process manually and reuse the session.
- Complex authenticated state — Preserve multi-step onboarding, two-factor authentication, or organization selection.
- Extension testing — Combine the profile with
path_to_extensionto test an extension with authenticated state.
The profile contains active session tokens. Add its directory to .gitignore and use a dedicated test account.
If you do not provide a Chrome profile, Shiplight creates a temporary profile and removes it when the session ends.
Use the profile in YAML tests
YAML tests provide the same option through userDataDir in the use: block. See Persistent Chrome Profile in the Fixtures reference. This option works for local runs on a computer that already has the profile. CI runners start from a clean checkout and cannot complete an interactive login, so use the shared-account pattern in CI.
Choose another authentication method
| Situation | Use |
|---|---|
| Simple username/password login | Let the agent log in and save the session |
| CI, where no one can complete SSO | Use saved storage state. See Authentication |
| A browser that is already open | Attach to the browser |