.. role:: bash(code)
   :language: bash

.. role:: js(code)
   :language: javascript

.. role:: python(code)
   :language: python

=============================
How to Test Migration Recipes
=============================

To test migration recipes, use the following mach command:

.. code-block:: bash

  ./mach fluent-migration-test python/l10n/fluent_migrations/bug_1485002_newtab.py

This will analyze your migration recipe to check that the :python:`migrate`
function exists, and interacts correctly with the migration context. Once that
passes, it clones :bash:`firefox-l10n-source` into :bash:`$OBJDIR/python/l10n`, creates a
reference localization by adding your local Fluent strings to the ones in
:bash:`firefox-l10n-source`. It then runs the migration recipe, both as dry run and
as actual migration. Finally it analyzes the commits, and checks if any
migrations were actually run and the bug number in the commit message matches
the migration name.

In most cases, a successful execution will only output the script execution:

.. code-block:: bash

  Running migration fluent_migrations.bug_1994180_fix_manage_extensions_reference for en-US
  Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
  Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 1
  Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
  Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 2

In some instance, the output after execution will include a diff if there are
differences between the migrated files and the reference content (blank lines
are automatically ignored). There are cases where a diff is still expected, even
if the recipe is correct:

- If the patch includes new strings that are not being migrated, the diff
  output will show these as removals. This occurs because the migration recipe
  test contains the latest version of strings from :bash:`firefox-l10n-source` with
  only migrations applied, while the reference file contains all string changes
  being introduced by the patch.
- If there are pending changes to FTL files included in the recipe that landed
  in the last few days, and haven't been pushed to :bash:`firefox-l10n-source` yet
  (they're in the :bash:`update` branch of :bash:`firefox-l10n-source`), these will
  show up as additions.

If a diff is displayed and the patch doesn't fall into the highlighted cases,
there may be an issue with the migration recipe. The example output below highlights
an instance where a migration failed to migrate a change to a string reference from
:bash:`{ unified-extensions-item-message-manage }` to
:bash:`{ unified-extensions-manage-extensions.label }`.

.. code-block:: bash

    Running migration fluent_migrations.bug_1994180_fix_manage_extensions_reference for en-US
    Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
    Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 1
    Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
    Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 2
  --- /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/reference/browser/browser/unifiedExtensions.ftl
  +++ /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl
  @@ -17,8 +17,8 @@
    unified-extensions-empty-reason-extension-not-enabled = You have extensions installed, but not enabled
    # In this headline, “Level up” means to enhance your browsing experience.
    unified-extensions-empty-reason-zero-extensions-onboarding = Level up your browsing with extensions
    -unified-extensions-empty-content-explain-enable2 = Select “{ unified-extensions-manage-extensions.label }” to enable them in settings.
    -unified-extensions-empty-content-explain-manage2 = Select “{ unified-extensions-manage-extensions.label }” to manage them in settings.
    +unified-extensions-empty-content-explain-enable2 = Select “{ unified-extensions-item-message-manage }” to enable them in settings.
    +unified-extensions-empty-content-explain-manage2 = Select “{ unified-extensions-item-message-manage }” to manage them in settings.
    unified-extensions-empty-content-explain-extensions-onboarding = Personalize { -brand-short-name } by changing how it looks and performs or boosting privacy and safety.

This diff output indicates that the string value being generated by the migration
(:bash:`Select “{ unified-extensions-item-message-manage }” to enable them in settings.`)
differs from the intended string value included in the Fluent file of the patch
(:bash: `{ unified-extensions-manage-extensions.label }`).

You can inspect the generated repository further by looking at

.. code-block:: bash

  ls $OBJDIR/python/l10n/bug_1485002_newtab/en-US

Caveats
-------

Be aware of hard-coded English context in migration. Consider for example:


.. code-block:: python

  ctx.add_transforms(
          "browser/browser/preferences/siteDataSettings.ftl",
          "browser/browser/preferences/siteDataSettings.ftl",
          transforms_from(
  """
  site-usage-persistent = { site-usage-pattern } (Persistent)
  """)
  )


This Transform will pass a manual comparison, since the two files are identical,
but will result in :js:`(Persistent)` being hard-coded in English for all
languages.

firefox-l10n-source repository
------------------------------

`firefox-l10n-source`_ is a unified repository including strings for all
shipping versions of Firefox, and is also used as a buffer before exposing strings
to localizers. There are typically two branches available, :bash:`main` and
:bash:`update`. The :bash:`main` branch acts as the source of truth for all
available strings exposed for localizaiton, while :bash:`update` acts as a
string quarantine. Migrations are run at the same time that strings are exposed
to localizers, that is when strings in :bash:`update` are merged into :bash:`main`.

When testing fluent recipes, the :bash:`fluent-migration-test` script relies on a
local clone of :bash:`firefox-l10n-source` located in :bash:`~/.mozbuild/l10n-source`.
When the mach command is run, the script either clones the remote repo if it doesn't
exist or pulls the latest changesets if :bash:`.git/l10n_pull_marker` is older than
2 days. Otherwise the current version is used.

Some advanced testing can be done by making changes in :bash:`~/.mozbuild/l10n-source`
such as checking out previous commits or adding strings manually. You can also force
sync to get the latest strings (if some have merged into :bash:`main` within the
2 day window) by manually pulling updates with git or by removing
:bash:`.git/l10n_pull_marker`.

.. _firefox-l10n-source: https://github.com/mozilla-l10n/firefox-l10n-source/
