Skip to main content

Documentation Index

Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Most tests need to be logged in before they do anything useful. There are three ways to handle that. Reach for them in this order: stay with live login while it is fast enough, then add an authSave / authLoad state file, and only move to a cached auth module when you need it. Wrap your login steps in a module and call it from the before section of each test. It logs in for real on every run, so the session is never stale and there is nothing to invalidate.
log-in.module.yaml
fileType: momentic/module/v2
id: log-in
name: Log in
steps:
  - type:
      text: "{{ env.USERNAME }}"
      into: Email input
  - type:
      text: "{{ env.PASSWORD }}"
      into: Password input
  - click: Log in
  - checkPageContains:
      text: Dashboard # verify the authenticated state
checkout.test.yaml
fileType: momentic/test/v2
id: checkout-flow
url: https://shop.example.com
before:
  - module: ../modules/log-in.module.yaml
steps:
  - act: Add a "Gravity Blanket" to the cart and check out
  - assert: The order confirmation page is shown
Prefer this whenever login is quick and not rate-limited. Move to one of the options below only when logging in on every run is too slow or trips auth-provider rate limits.
Running the test from a step in the main body (a common thing to do while editing) skips the before section, so the login never runs and the first step lands on a logged-out page. Run the whole test to exercise the before section. See Before and after sections.

​
2. Save and restore a state file (authSave / authLoad)

The authSave and authLoad steps (the editor’s Save auth state / Load auth state) write and read the browser’s cookies, localStorage, and IndexedDB to a JSON file you manage yourself. This is the closest analog to Playwright’s storageState, so it is the natural next step if you are migrating from Playwright: log in once, save the state, and load it instead of logging in again.
checkout.test.yaml
before:
  - authLoad: ./auth-state.json
after:
  - authSave: ./auth-state.json
The file is portable and version-controllable: you can generate it in a setup step, commit a fixture, or hand it to a non-Momentic tool. The trade-off is that you own its freshness - refresh it when the saved session expires.

​
3. Cached auth module

When you want the speed-up without managing a file, let Momentic cache the session for you. Mark the login module as an auth module and enable caching: the first run logs in for real, and later runs (and parallel tests sharing the same cache key) restore the saved browser state server-side and skip the login steps entirely.
log-in.module.yaml
fileType: momentic/module/v2
id: log-in
name: Log in
autoAuth: true # "Treat as auth module" - save & restore cookies/localStorage/IndexedDB
defaultCacheAllInvocations: true # "Cache globally" - reuse across tests
defaultCacheKey: admin-user # parallel tests sharing this key reuse one session
defaultCacheTtl: 3600000 # expire after 1 hour (shorter than the session lifetime)
steps:
  - type:
      text: "{{ env.USERNAME }}"
      into: Email input
  - type:
      text: "{{ env.PASSWORD }}"
      into: Password input
  - click: Log in
  - checkPageContains:
      text: Dashboard # verify the authenticated state so the cache only saves on success
Call it from the before section exactly like the live-login module. This is the fastest option at scale (parallel tests reuse one session) and Momentic handles capture, storage, expiry, and per-key isolation for you. See Cache authenticated sessions for the full walkthrough and Modules for every cache field.
Don’t combine authSave / authLoad with a cached auth module for the same session - both save and restore state, and doing both leads to stale or conflicting auth. Pick one.

​
Options and trade-offs

StrategyWhen it runsTrade-offs
Live login (recommended)Every run (whole-test runs only)Most reliable, never stale. Logs in every run, so slower and can hit rate limits.
authSave / authLoad state fileWhenever you place the stepsPortable JSON, like Playwright’s storageState. You own refreshing it when it stales.
Cached auth module (autoAuth + caching)Once per cache key, within the TTLFastest at scale; parallel tests reuse one session. Needs a cache key and expiry.

​
In CI

Live login works in CI with no extra setup - just provide credentials as secrets (env.USERNAME, env.PASSWORD, OTP secrets) rather than committed values. If logging in every run is too slow, add an authSave / authLoad state file or a cached auth module; the module’s session is stored server-side alongside the step cache, so once one run logs in, other runs and shards can reuse it within the TTL.

​
SSO, 2FA, and provisioned inboxes

Avoid logging in through SSO providers (Google, Facebook, GitHub). They often block automated browsers.
For one-time codes and magic links, fetch the code in a JavaScript step and save it to the environment: