MAINT: Clarify migration tests and documentation

Author: GibranAlfa

src/fmu/settings/_migrations/README.md

@@ -95,26 +95,27 @@ The following example changes the current `ProjectConfig` from schema version 1
 ### 1. Update the current model
 
 Edit the existing model in `models/project_config.py`. Do not create a second
-`ProjectConfig` class. The `...` lines below represent all unchanged fields in the
-current model, such as `version`, `created_at`, `created_by`, `masterdata`, and
-`rms`. Only the schema version and the renamed field change in this example:
+`ProjectConfig` class. Some existing fields and default values are not shown in the
+shortened example. The comments show where they belong. These fields include `version`,
+`created_at`, `created_by`, `masterdata`, and `rms`. Only the schema version and the
+renamed field change in this example:
 
 ```python
 class ProjectConfig(ResettableBaseModel):
     """The configuration file in a .fmu directory."""
 
     schema_version: Literal[2] = 2
-    # ... unchanged fields ...
+    # Existing fields before this field are not shown in this example.
     max_cache_revisions: int = Field(default=10, ge=5)
-    # ... unchanged fields ...
+    # Existing fields after this field are not shown in this example.
 
     @classmethod
     def reset(cls: type[Self]) -> Self:
         """Reset the configuration to its defaults."""
         return cls(
-            # ... unchanged defaults ...
+            # Existing default values before this one are not shown.
             max_cache_revisions=10,
-            # ... unchanged defaults ...
+            # Existing default values after this one are not shown.
         )
 ```
 

tests/test_migrations/test_migration_manager.py

@@ -80,8 +80,11 @@ def test_migration_manager_applies_all_steps_without_mutating_input() -> None:
         value="old",
         migrations_applied=[1, 2],
     )
-    assert data["migrations_applied"] == []
-    assert data["schema_version"] == 1
+    assert data == {
+        "schema_version": 1,
+        "value": "old",
+        "migrations_applied": [],
+    }
 
 
 def test_migration_manager_treats_missing_version_as_version_one() -> None:
@@ -106,6 +109,72 @@ def test_migration_manager_treats_missing_version_as_version_one() -> None:
     assert "schema_version" not in data
 
 
+def test_migration_manager_adds_legacy_version_to_returned_model() -> None:
+    """Unversioned data returns a version-one model without changing the input."""
+    data = {"value": "old"}
+    manager = MigrationManager(VersionOneModel, {})
+
+    result = manager.migrate_resource(data)
+
+    assert result == VersionOneModel(schema_version=1, value="old")
+    assert data == {"value": "old"}
+
+
+@pytest.mark.parametrize(
+    ("data", "expected"),
+    [
+        ({"schema_version": 3}, False),
+        ({"schema_version": 2}, True),
+        ({}, True),
+    ],
+)
+def test_migration_manager_reports_when_migration_is_required(
+    data: dict[str, Any],
+    expected: bool,
+) -> None:
+    """The requirement check compares stored and current schema versions."""
+    manager = MigrationManager(
+        VersionThreeModel,
+        {
+            1: migrate_one_to_two,
+            2: migrate_two_to_three,
+        },
+    )
+
+    assert manager.requires_migration(data) is expected
+
+
+def test_requires_migration_rejects_missing_step() -> None:
+    """The requirement check rejects an incomplete migration path."""
+    manager = MigrationManager(
+        VersionThreeModel,
+        {2: migrate_two_to_three},
+    )
+
+    with pytest.raises(
+        MigrationError,
+        match=(
+            "Missing VersionThreeModel migration function for stored data from "
+            "schema version 1 to 2"
+        ),
+    ):
+        manager.requires_migration({"schema_version": 1})
+
+
+def test_requires_migration_rejects_newer_schema() -> None:
+    """The requirement check rejects stored data from a newer schema."""
+    manager = MigrationManager(VersionThreeModel, {})
+
+    with pytest.raises(
+        MigrationError,
+        match=(
+            "Stored VersionThreeModel data has schema version 4, which is newer "
+            "than supported version 3"
+        ),
+    ):
+        manager.requires_migration({"schema_version": 4})
+
+
 def test_migration_manager_rejects_missing_step() -> None:
     """Every intermediate migration must be registered."""
     manager = MigrationManager(

tests/test_migrations/test_resource_migration.py

@@ -19,7 +19,7 @@
 from fmu.settings.models.project_config import ProjectConfig
 
 if TYPE_CHECKING:
-    from fmu.settings._fmu_dir import ProjectFMUDirectory, UserFMUDirectory
+    from fmu.settings._fmu_dir import ProjectFMUDirectory
 
 
 class VersionTwoResource(BaseModel):
@@ -106,10 +106,10 @@ def test_save_after_migration_backs_up_old_content(
     assert {"schema_version": 2, "value": "updated"} in cached_data
 
 
-def test_cached_old_schema_is_readable_and_restorable(
+def test_cached_version_one_content_can_be_read_and_restored(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
-    """Existing cache APIs migrate an old backup before using its content."""
+    """Reading or restoring the revision migrates its content to version two."""
     manager = MigratableResourceManager(fmu_dir)
     old_content = json.dumps({"schema_version": 1, "value": "old"}, indent=2)
     fmu_dir.write_text_file(manager.relative_path, old_content)
@@ -141,10 +141,10 @@ def test_cached_old_schema_is_readable_and_restorable(
     }
 
 
-def test_cache_read_rejects_newer_schema_with_resource_context(
+def test_cache_manager_cannot_read_content_from_a_newer_schema_version(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
-    """A cache migration error identifies the affected resource."""
+    """A version-two manager cannot read a cached version-three revision."""
     manager = MigratableResourceManager(fmu_dir)
     revision = fmu_dir.cache.store_revision(
         manager.relative_path,
@@ -167,27 +167,6 @@ def test_cache_read_rejects_newer_schema_with_resource_context(
         )
 
 
-def test_force_load_without_store_cache_preserves_existing_cached_model(
-    fmu_dir: ProjectFMUDirectory,
-) -> None:
-    """A forced migrated read can avoid replacing the in-memory cache."""
-    manager = MigratableResourceManager(fmu_dir)
-    fmu_dir.write_text_file(
-        manager.relative_path,
-        json.dumps({"schema_version": 1, "value": "first"}),
-    )
-    cached = manager.load()
-    fmu_dir.write_text_file(
-        manager.relative_path,
-        json.dumps({"schema_version": 1, "value": "second"}),
-    )
-
-    reloaded = manager.load(force=True, store_cache=False)
-
-    assert reloaded == VersionTwoResource(value="second")
-    assert manager._cache == cached
-
-
 def test_migration_save_respects_lock_before_backup(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
@@ -268,10 +247,17 @@ def test_current_schema_save_does_not_add_migration_backup(
     assert not fmu_dir.get_file_path("migration-backups").exists()
 
 
-def test_save_replaces_non_object_json_without_migration_backup(
+def test_save_overwrites_non_object_json_without_a_migration_backup(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
-    """A valid model can replace non-object JSON without preserving it."""
+    """Allow a valid save when the existing resource contains a JSON list.
+
+    For example, the existing file contains only ``[]`` instead of the expected JSON
+    object. The list has no schema version, so it cannot be migrated and is not
+    saved as a migration backup. The valid version-two model replaces the list with
+    ``{"schema_version": 2, "value": "current"}``, and only this replacement is
+    added to the normal cache.
+    """
     manager = MigratableResourceManager(fmu_dir)
     fmu_dir.write_text_file(manager.relative_path, json.dumps([]))
 
@@ -287,12 +273,13 @@ def test_save_replaces_non_object_json_without_migration_backup(
         "schema_version": 2,
         "value": "current",
     }
+    assert not fmu_dir.get_file_path("migration-backups").exists()
 
 
-def test_save_rejects_newer_stored_schema_before_overwrite(
+def test_save_does_not_overwrite_a_newer_stored_version(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
-    """A save does not overwrite stored data from a newer schema."""
+    """A version-two manager rejects version-three data before writing or caching."""
     manager = MigratableResourceManager(fmu_dir)
     future_content = json.dumps({"schema_version": 3, "value": "future"})
     fmu_dir.write_text_file(manager.relative_path, future_content)
@@ -345,35 +332,37 @@ def test_load_rejects_non_object_resource(
         manager.load()
 
 
-def test_project_resource_managers_have_version_one_migration_managers(
-    fmu_dir: ProjectFMUDirectory,
+@pytest.mark.parametrize(
+    ("directory_fixture", "resource_name"),
+    [
+        ("fmu_dir", "config"),
+        ("fmu_dir", "mappings"),
+        ("user_fmu_dir", "config"),
+    ],
+)
+def test_resource_has_version_one_migration_manager(
+    request: pytest.FixtureRequest,
+    directory_fixture: str,
+    resource_name: str,
 ) -> None:
-    """Project resources are wired without a dummy version two."""
-    managers = [
-        fmu_dir.config.migration_manager,
-        fmu_dir.mappings.migration_manager,
-    ]
-
-    assert all(manager is not None for manager in managers)
-    assert all(manager.current_version == 1 for manager in managers if manager)
-    assert all(manager.migrations == {} for manager in managers if manager)
+    """Check the current schema version and migrations for each resource.
 
-
-def test_user_config_has_version_one_migration_manager(
-    user_fmu_dir: UserFMUDirectory,
-) -> None:
-    """User config is wired without a dummy version two."""
-    manager = user_fmu_dir.config.migration_manager
+    Project config, user config, and mappings currently use schema version one, so
+    their migration registries are empty. Update this test when a resource gets a
+    new schema version and migration function.
+    """
+    fmu_directory = request.getfixturevalue(directory_fixture)
+    manager = getattr(fmu_directory, resource_name).migration_manager
 
     assert manager is not None
     assert manager.current_version == 1
     assert manager.migrations == {}
 
 
-def test_project_config_cache_boundary_handles_unversioned_revision(
+def test_unversioned_project_config_can_be_read_and_restored_from_cache(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
-    """Project cache APIs normalize and restore an unversioned config revision."""
+    """Legacy config restores version-one data, runtime settings, and changelog."""
     legacy_config = fmu_dir.config.load().model_dump(mode="json")
     legacy_config.pop("schema_version")
     legacy_config["cache_max_revisions"] = 7
@@ -397,10 +386,10 @@ def test_project_config_cache_boundary_handles_unversioned_revision(
     assert fmu_dir.changelog.load().root[-1].change_type == ChangeType.restore
 
 
-def test_mappings_cache_boundary_handles_unversioned_revision(
+def test_unversioned_mappings_can_be_read_and_restored_from_cache(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
-    """Project cache APIs use the mappings migration manager across the union."""
+    """Legacy mappings restore as version one and add a changelog entry."""
     legacy_mappings = InternalMappings().model_dump(mode="json")
     legacy_mappings.pop("schema_version")
     revision = fmu_dir.cache.store_revision(
@@ -419,10 +408,10 @@ def test_mappings_cache_boundary_handles_unversioned_revision(
     assert fmu_dir.changelog.load().root[-1].change_type == ChangeType.restore
 
 
-def test_resource_manager_rejects_mismatched_migration_model(
+def test_resource_manager_rejects_migration_functions_for_another_model(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
-    """A resource manager cannot use migrations for a different model."""
+    """The migration and resource managers must use the same Pydantic model."""
     migration_manager = MigrationManager(
         VersionTwoResource,
         {1: migrate_one_to_two},