Skip to main content
momentic-mobile 1.0 drops Node.js 20 and changes how test videos are recorded. This guide covers the breaking changes and how to upgrade.
This guide is for the mobile CLI (momentic-mobile). The web CLI (momentic) has its own v3 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 and checks the result against an existing mobile test.

​
1. Use a supported Node.js version

momentic-mobile 1.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 mobile project root, preview the changes first:
The preview needs a valid saved login or MOMENTIC_API_KEY. Check it with npx momentic-mobile@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-mobile@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 mobile 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. 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-mobile 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-mobile 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.

​
Breaking changes

--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.

​
Other changes

These need no action:
  • AI action steps default to the V3 agent. Existing steps continue to run unchanged.
  • momentic-mobile init writes recommended AI agent 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.

​
3. Validate and update CI

Validate the rewritten files, then run an existing test with the same app build, device settings, environment, and test data as 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 Mobile version pins in CI, then install from the committed lockfile and invoke the project CLI. Mobile tests do not need a browser reinstallation; retain the iOS or Android toolchain required by your tests.