Skip to main content
momentic 3.0 drops Node.js 20, retires the legacy v1 AI agents, and removes a few config options that are now handled automatically. This guide covers the breaking changes and how to upgrade.
This guide is for the web CLI (momentic). Mobile (momentic-mobile) has its own v1 upgrade guide. If your repo has both, upgrade each separately. When they share a configuration, follow the simplified-format guide to rewrite both platforms’ files; one upgrade does not convert the other platform.

​
Migrate with a coding agent

Paste this prompt into your coding agent. It runs the upgrade, reinstalls the browsers, and checks the result against an existing test.

​
1. Use a supported Node.js version

momentic 3.0 requires Node.js 22.12.0 or later in the 22.x line, or 24.0.0 or later. Node.js 20 and 23 are unsupported. Check your version:
Update the Node version in your CI images and any .nvmrc / engines field before upgrading.

​
2. Run the upgrade

Save your current configuration, tests, package.json, and lockfile before upgrading. Check git status --short and keep unrelated changes separate so you can recover from a partial rewrite. If the upgrade changes the file format, coordinate with collaborators and have them rebase after it lands. From your web project root, preview the changes first:
The preview needs a valid saved login or MOMENTIC_API_KEY. Check it with npx momentic@latest whoami; see authentication if it fails. --dry-run skips the package installation, project file writes, and snapshot uploads. Review the preview, then apply the upgrade:
Invoke momentic@latest so the rewrite uses the current serializer. Updating the package during a command does not replace that command’s running process. Use --config <path> if project discovery finds more than one configuration. The command installs the CLI as a development dependency and updates the project configuration. For a legacy-format project, it rewrites web tests and modules and sets fileFormat: v2. It also updates ai.agentConfig: entries that match the recommendation or start with it followed by . stay unchanged. Other versions, including older exact pins, change to the recommendation. It sets ai.useMemory: true and ai.failureRecovery: true, even if you previously disabled them. Review those changes before running tests. Browser settings are not part of this AI refresh. When the config already says fileFormat: v2, upgrade skips the YAML rewrite. If legacy files remain, first recover from any partial migration, then use momentic migrate simplified-format. If the format and AI settings are already current, project files stay unchanged; the package installation can still update the CLI. See momentic upgrade.
The upgrade is not atomic. It installs the CLI before rewriting project files. If serialization fails, some files may already have changed. Revert the changes made by that upgrade attempt, fix the reported error, and rerun. Preserve unrelated work; reinstall the previous dependency version if you need to restore the pre-upgrade installation.

​
3. Reinstall your browsers

momentic 3.0 pins newer browser builds than earlier releases. momentic upgrade does not download them. If your tests launch browsers locally, binaries installed for the previous build can fail to launch, so reinstall them after upgrading:
Pass whichever browsers your tests use (chromium, chrome, or chrome-for-testing), or --all to install every supported browser. See momentic install-browsers for details.

​
Breaking changes

Each of these requires an edit if your project uses the affected feature:
  • Legacy v1 AI agents removed. The v1 locator, assertion, visual assertion, and text extraction agents have been retired. A run that pins one of these in ai.agentConfig in momentic.config.yaml now errors; switch those entries to a current version (see AI configuration).
  • browser.bustCacheOnBoundingBoxChange removed. Momentic validates cached locators without this option. Remove it from momentic.config.yaml.
  • --record-video flag removed. Use --video instead (--video true to keep every recording, --video false to disable). Recording now defaults to on-fail: a video is captured for every run but kept only when the test fails. An explicit recordVideo setting or --video flag overrides this default.
  • AI action steps default to the V3 agent. The older V2 agent is marked “Legacy” and can no longer be selected for new AI action steps in the editor. Existing V2 steps continue to run unchanged.

​
Browser and agent defaults

Hybrid selectors default to prefer when browser.hybridSelectorMode is unset, including in existing projects. Set it explicitly to override that default. momentic init also writes browser.disableSecondaryCacheResolution: true and recommended ai.agentConfig versions for new projects. It does not rewrite an existing configuration. Current agent defaults can use a major version; pin an exact supported sub-version when you need that revision to stay fixed. See AI configuration.

​
4. Validate and update CI

Validate the rewritten files, then run an existing test against the same target and test data used before upgrading. Replace the example path with your test:
Inspect the run result, recovery activity, and failure classifications before changing the test. Then run the affected suite and confirm the expected tests and parameterized cases actually ran. Account for disabled or skipped tests and quarantine; exit code 0 alone does not prove equivalent behavior. Once the checks pass, review and commit momentic.config.yaml, rewritten tests and modules, package.json, and the lockfile together. Update explicit Momentic version pins in CI, then install from the committed lockfile and invoke the project CLI. If CI launches browsers locally, reinstall the selected browsers with that version too.