Momentic can help you migrate from V1 to V2. However, some manual changes to your CI setup are required. Each project in your repository must be migrated separately.

​
Migration procedure

Step 1: Update Momentic version.

Update CI scripts, package.json, Makefiles, and any other files in your codebase that reference the momentic CLI version to the latest 2.x version. Run install using your package manager to update dependencies and lock files.

We strongly recommend pinning the version of the momentic in your codebase. Otherwise, breaking releases will immediately affect your CI pipelines.

Step 2: Run the migration wizard.

This command will update your momentic.config.yaml to include feature flags, Git branch configuration, and AI agent settings.

npx momentic migrate v1-v2

Step 3: Run checks for duplicate IDs.

CLI V2 fails if it detects duplicate command or step IDs in your repository. Duplicate IDs are caused by manually modifying or copy-pasting tests outside of the Momentic editor, and can lead to flakiness.

To check whether your existing repository has duplicate IDs, run the following command. Problems can be automatically fixed by adding the --fix flag. The first run after the duplicate IDs are fixed might take longer than normal.

npx momentic check duplicate-ids

Step 4: Update CI scripts to install browsers.

Browsers must be explicitly installed in V2.

If your CI scripts do not already invoke the install-browsers command, add this command before any tests are executed.

You can determine which browsers to install by searching your codebase for the browserType string. See the install-browsers command for more information.

Step 5: Update CI scripts to upload results.

momentic run now saves all test results to the directory specified in the --output-dir option, or the test-results folder if unset.

For the results to be available on Momentic Cloud, add a step to run the momentic results upload <folder> command, supplying the path to the directory containing the local test results.

For example, assuming you did not set the --output-dir option when invoking momentic run, add the following line to your CI pipeline:

npx momentic results upload test-results

See the results command for more information and details on merging results for sharding setups.

Step 6: Change deprecated options and commands.

Since writing test results locally is now the default, the --report and --no-report flags are no longer supported. If reporting is not desired, simply do not run the momentic results upload command. Similarly, setting the CI=true environment variable is no longer necessary and can be removed from CI scripts.

Finally, to ensure consistency, CLI V2 renamed the following commands. Adjust them in your CI scripts if necessary:

momentic import-from-cloud -> momentic import
momentic check-config -> momentic check config

Step 7: Commit changes and run CI.

Commit all changes made in previous steps and create a new pull request using your source control system. Ensure that this pull request kicks off all Momentic tests in your repository to verify the new changes.

Step 8: Address any test failures.

Diagnose and correct any test failures on your pull request.

The primary reason expected for failing tests after an upgrade attempt is the change in tab switching behavior: switching to newly opened tabs no longer occurs automatically in the Momentic CLI, as this behavior is inherently racy and flaky.

Momentic recommends adding explicit Switch Tab steps instead. If this is not possible, you can set the autoFollowNewTabs option to true in the browser section of your momentic.config.yaml as a last resort.

Step 9: Merge changes and notify the team.

Notify the rest of the team to rebase as soon as possible; using different major versions of Momentic at the same time is not recommended.