Draft: Add command behaviour tests

src/deploy_tools/compare.py

@@ -87,10 +87,15 @@ def _reconstruct_deployment_config_from_modules(layout: Layout) -> Deployment:
     Note that the default versions will be different to those in initial configuration.
     """
     releases = _collect_releases(layout)
-    default_versions = _collect_default_modulefile_versions(layout, list(releases))
-    settings = DeploymentSettings(default_versions=default_versions)
+    deployment = Deployment(settings=DeploymentSettings(), releases=releases)
 
-    return Deployment(settings=settings, releases=releases)
+    # Only non-deprecated (live) modules are associated with a .version file
+    live_names = list(deployment.get_final_deployed_modules())
+    deployment.settings.default_versions = _collect_default_modulefile_versions(
+        layout, live_names
+    )
+
+    return deployment
 
 
 def _collect_releases(layout: Layout) -> ReleasesByNameAndVersion:
@@ -152,7 +157,12 @@ def _collect_default_modulefile_versions(
     default_versions: dict[str, str] = {}
 
     for name in names:
-        default_version = get_default_modulefile_version(name, layout)
+        try:
+            default_version = get_default_modulefile_version(name, layout)
+        except FileNotFoundError as exc:
+            raise ComparisonError(
+                f"Live module '{name}' has no default version file"
+            ) from exc
         if default_version is not None:
             default_versions[name] = default_version
 
@@ -194,4 +204,6 @@ def _get_dict_diff(d1: dict[str, Any], d2: dict[str, Any]) -> str:
 
 def _yaml_dumps(obj: dict[str, Any], indent: int | None = None) -> str:
     ta = TypeAdapter(dict[str, Any])
-    return yaml.safe_dump(ta.dump_python(obj), indent=indent)
+    # Dump in JSON mode so pydantic special types (e.g. AnyUrl) are coerced to YAML-safe
+    # primitives
+    return yaml.safe_dump(ta.dump_python(obj, mode="json"), indent=indent)

src/deploy_tools/deploy.py

@@ -1,5 +1,4 @@
 import logging
-import os
 import shutil
 from pathlib import Path
 
@@ -69,7 +68,7 @@ def _deploy_new_releases(to_add: list[Release], layout: Layout) -> None:
         mf_link = layout.get_modulefile_link(name, version, from_deprecated=deprecated)
 
         mf_link.parent.mkdir(parents=True, exist_ok=True)
-        os.symlink(modulefile, mf_link)
+        mf_link.symlink_to(modulefile)
 
 
 def _deploy_releases(
@@ -155,6 +154,10 @@ def _delete_modulefiles_name_folder(
 ) -> None:
     modulefiles_name_path = layout.get_modulefiles_root(from_deprecated) / name
 
+    # Handle several versions of the same module being processed together
+    if not modulefiles_name_path.exists():
+        return
+
     # Ignore the default version file when checking for existing modulefile links
     if next(modulefiles_name_path.glob(MODULE_VERSIONS_GLOB), None) is None:
         shutil.rmtree(modulefiles_name_path)

src/deploy_tools/layout.py

@@ -62,7 +62,6 @@ class Layout:
     DEFAULT_VERSION_FILENAME = ".version"
 
     DEPLOYMENT_SNAPSHOT_FILENAME = "deployment.yaml"
-    PREVIOUS_DEPLOYMENT_SNAPSHOT_FILENAME = "previous-deployment.yaml"
 
     def __init__(self, deployment_root: Path, build_root: Path | None = None) -> None:
         self._root = deployment_root

src/deploy_tools/models/save_and_load.py

@@ -5,6 +5,7 @@
 
 import yaml
 from pydantic import BaseModel
+from pydantic import ValidationError as PydanticValidationError
 
 from ..errors import DeployToolsError
 from .deployment import (
@@ -67,18 +68,20 @@ def _load_release(path: Path) -> Release:
     if path.is_dir() or not path.suffix == YAML_FILE_SUFFIX:
         raise LoadError(f"Unexpected file in configuration directory:\n{path}")
 
-    with open(path) as f:
-        return load_from_yaml(Release, f)
+    try:
+        with open(path) as f:
+            return load_from_yaml(Release, f)
+    except (OSError, yaml.YAMLError, PydanticValidationError, TypeError) as exc:
+        # Include exc: under the top-level handler the traceback (and chained cause) is
+        # suppressed, so the failing field is only visible if surfaced in the message.
+        raise LoadError(f"Module configuration is invalid:\n{path}\n{exc}") from exc
 
 
 def _check_filepath_matches(version_path: Path, module: Module) -> None:
     """Ensure the Module's file path (in config folder) matches the metadata.
 
     It should be the Module's name and version as /<config_folder>/<name>/<version>.yaml
     """
-    if version_path.is_dir() and version_path.suffix == YAML_FILE_SUFFIX:
-        raise LoadError(f"Module directory has incorrect suffix:\n{version_path}")
-
     if not module.name == version_path.parent.name:
         raise LoadError(
             f"Module name {module.name} does not match path:\n{version_path}"

src/deploy_tools/modulefile.py

@@ -60,6 +60,8 @@ def apply_default_versions(
                 overwrite=True,
             )
         else:
+            # Defensive: remove a stale default file for a deployed module that has no
+            # entry in the default map. This ought to be unreachable via the CLI
             default_version_file.unlink(missing_ok=True)
 
 

src/deploy_tools/snapshot.py

@@ -1,7 +1,9 @@
 import io
 import logging
 
-from git import Repo
+import yaml
+from git import BadName, Repo
+from pydantic import ValidationError as PydanticValidationError
 
 from .errors import DeployToolsError
 from .layout import Layout
@@ -54,14 +56,25 @@ def load_snapshot(layout: Layout, from_scratch: bool = False) -> Deployment:
         )
 
     logger.debug("Loading snapshot: %s", layout.deployment_snapshot_path)
-    with open(layout.deployment_snapshot_path) as f:
-        return load_from_yaml(Deployment, f)
+    try:
+        with open(layout.deployment_snapshot_path) as f:
+            return load_from_yaml(Deployment, f)
+    except (OSError, yaml.YAMLError, PydanticValidationError, TypeError) as exc:
+        raise SnapshotError(
+            f"Deployment snapshot could not be read:\n{layout.deployment_snapshot_path}"
+        ) from exc
 
 
 def load_snapshot_from_ref(layout: Layout, ref: str) -> Deployment:
     """Load the deployment snapshot from the given git ref of the deployment area."""
     logger.debug("Loading snapshot from ref: %s", ref)
-    repo = Repo(layout.deployment_root)
-    ref_snapshot = repo.commit(ref).tree[layout.DEPLOYMENT_SNAPSHOT_FILENAME]
-    with io.BytesIO(ref_snapshot.data_stream.read()) as snapshot_f:  # type: ignore
-        return load_from_yaml(Deployment, snapshot_f)
+    with Repo(layout.deployment_root) as repo:
+        try:
+            ref_snapshot = repo.commit(ref).tree[layout.DEPLOYMENT_SNAPSHOT_FILENAME]
+        except (BadName, KeyError) as exc:
+            raise SnapshotError(
+                f"Deployment snapshot not found at git ref:\n{ref}"
+            ) from exc
+
+        with io.BytesIO(ref_snapshot.data_stream.read()) as snapshot_f:  # type: ignore
+            return load_from_yaml(Deployment, snapshot_f)

src/deploy_tools/sync.py

@@ -1,11 +1,12 @@
 import logging
 from pathlib import Path
 
-from git import Repo
+from git import InvalidGitRepositoryError, Repo
 
 from .build import build, clean_build_area
 from .deploy import deploy_changes
-from .layout import Layout
+from .errors import DeployToolsError
+from .layout import Layout, ModuleBuildLayout
 from .models.save_and_load import load_deployment
 from .snapshot import create_snapshot, load_snapshot
 from .templater import Templater, TemplateType
@@ -15,7 +16,17 @@
 
 logger = logging.getLogger(__name__)
 
-IGNORE_DIRS = ["/build", "/modules/*/*/sif_files"]
+
+class SyncError(DeployToolsError):
+    """Raised when the deployment area is not in a state the sync process can use."""
+
+
+# Files not tracked in the deployment area's git repo (kept only as a change reference):
+# the transient build area and the large Apptainer .sif images.
+IGNORE_DIRS = [
+    f"/{Layout.DEFAULT_BUILD_ROOT_NAME}",
+    f"/{Layout.MODULES_ROOT_NAME}/*/*/{ModuleBuildLayout.SIF_FILES_FOLDER}",
+]
 
 
 def synchronise(
@@ -45,18 +56,25 @@ def synchronise(
         logger.info("Creating git repository in deployment area")
         repo = _initialise_git_repo(layout.deployment_root, IGNORE_DIRS)
     else:
-        repo = Repo(layout.deployment_root)
-
-    logger.info("Creating snapshot")
-    create_snapshot(deployment, layout)
-
-    logger.info("Deploying changes")
-    deploy_changes(deployment_changes, layout)
-
-    logger.info("Committing changes to git (for reference)")
-    repo.git.add("--all")
-    commit = repo.index.commit("Performed sync process")
-    logger.info("Commit SHA: %s", commit.hexsha)
+        try:
+            repo = Repo(layout.deployment_root)
+        except InvalidGitRepositoryError as exc:
+            raise SyncError(
+                f"Deployment area has a snapshot but is not a git repository "
+                f"(git metadata missing or corrupt):\n{layout.deployment_root}"
+            ) from exc
+
+    with repo:
+        logger.info("Creating snapshot")
+        create_snapshot(deployment, layout)
+
+        logger.info("Deploying changes")
+        deploy_changes(deployment_changes, layout)
+
+        logger.info("Committing changes to git (for reference)")
+        repo.git.add("--all")
+        commit = repo.index.commit("Performed sync process")
+        logger.info("Commit SHA: %s", commit.hexsha)
 
     logger.info("Sync process finished")
 

src/deploy_tools/validate.py

@@ -157,11 +157,11 @@ def _get_release_changes(
     return release_changes
 
 
-def _validate_added_modules(releases: list[Release], from_scratch: bool) -> None:
+def _validate_added_modules(releases: list[Release], allow_all: bool) -> None:
     for release in releases:
         module = release.module
         if release.deprecated:
-            if not from_scratch:
+            if not allow_all:
                 raise ValidationError(
                     f"Module {module.name}/{module.version} cannot have deprecated "
                     f"status on initial creation."

tests/configs/README.md

@@ -0,0 +1,16 @@
+# Test configurations
+
+Sample `deploy-tools` configuration folders used by the test suite, grouped by purpose:
+
+- **`golden-master/`** — the `01-initial` … `06-removed` lifecycle sequence. These are
+  **cumulative and ordered**: each stage is synced on top of the previous one to model a
+  real deployment lifecycle (only `01-initial` uses `--from-scratch`). Driven by
+  `test_golden_master.py` and regenerated by `generate_samples.sh`. Do not reorder or make
+  independent.
+- **`valid/`** — standalone, self-contained configs that should deploy/validate cleanly,
+  each serving one focused test (e.g. `minimal`, `empty`, `multi-version-active`).
+- **`invalid/`** — configs that a command must reject; each maps to a test asserting the
+  specific error message.
+
+When adding a fixture, prefer reusing an existing one; otherwise add a single-purpose
+folder under `valid/` or `invalid/`. Leave `golden-master/` to the lifecycle sequence.

tests/configs/invalid/default-version-not-deployed/example-module-shell/1.0.yaml

@@ -0,0 +1,13 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json
+
+module:
+  name: example-module-shell
+  version: "1.0"
+  description: Minimal shell-only module used by the validate tests
+
+  applications:
+    - app_type: shell
+
+      name: test-shell-echo
+      script:
+        - echo hello

tests/configs/invalid/default-version-not-deployed/settings.yaml

@@ -0,0 +1,4 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/deployment-settings.json
+
+default_versions:
+  example-module-shell: "2.0"

tests/configs/invalid/deprecated-on-creation/example-module-shell/1.0.yaml

@@ -0,0 +1,13 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json
+
+module:
+  name: example-module-shell
+  version: "1.0"
+  description: Minimal shell-only module used by the validate tests
+
+  applications:
+    - app_type: shell
+
+      name: test-shell-echo
+      script:
+        - echo hello

tests/configs/invalid/deprecated-on-creation/example-module-shell/2.0.yaml

@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json
+
+module:
+  name: example-module-shell
+  version: "2.0"
+  description: Minimal shell-only module used by the validate tests
+
+  applications:
+    - app_type: shell
+
+      name: test-shell-echo
+      script:
+        - echo hello
+
+deprecated: true

tests/configs/invalid/deprecated-on-creation/settings.yaml

@@ -0,0 +1,3 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/deployment-settings.json
+
+default_versions: {}

tests/configs/invalid/invalid-module-name/example-module-shell/1.0.yaml

@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json
+
+# The module name contains a dot, which MODULE_NAME_REGEX forbids; loading must fail
+# with a clear LoadError that names the offending field.
+module:
+  name: example.module.shell
+  version: "1.0"
+  description: Module with a name that violates the name constraint
+
+  applications:
+    - app_type: shell
+
+      name: test-shell-echo
+      script:
+        - echo hello

tests/configs/invalid/invalid-module-name/settings.yaml

@@ -0,0 +1,3 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/deployment-settings.json
+
+default_versions: {}

tests/configs/invalid/invalid-shell-script/example-module-shell/1.0.yaml

@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json
+
+module:
+  name: example-module-shell
+  version: "1.0"
+  description: Module whose shell script is not valid bash
+
+  applications:
+    - app_type: shell
+
+      name: test-shell-echo
+      # 'fi' with no matching 'if' is invalid bash, so `validate --test-build` must
+      # reject the generated entrypoint when it runs `bash -n` over it.
+      script:
+        - fi

tests/configs/invalid/invalid-shell-script/settings.yaml

@@ -0,0 +1,3 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/deployment-settings.json
+
+default_versions: {}

tests/configs/invalid/modified-without-allow-updates/example-module-shell/1.0.yaml

@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json
+
+module:
+  name: example-module-shell
+  version: "1.0"
+  description: Minimal shell-only module used by the validate tests
+
+  applications:
+    - app_type: shell
+
+      name: test-shell-echo
+      # Differs from the valid/minimal baseline (echo hello) so that deploying this over
+      # it is an in-place modification, rejected without allow_updates / a version bump.
+      script:
+        - echo modified

tests/configs/invalid/modified-without-allow-updates/settings.yaml

@@ -0,0 +1,3 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/deployment-settings.json
+
+default_versions: {}

tests/configs/invalid/name-mismatch/settings.yaml

@@ -0,0 +1,3 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/deployment-settings.json
+
+default_versions: {}

tests/configs/invalid/name-mismatch/wrong-folder-name/1.0.yaml

@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json
+
+# The module name does not match its parent folder (wrong-folder-name), which the
+# loader requires to match.
+module:
+  name: example-module-shell
+  version: "1.0"
+  description: Module whose name does not match its containing folder
+
+  applications:
+    - app_type: shell
+
+      name: test-shell-echo
+      script:
+        - echo hello