Files
computer-playbook/tests/unit/cli/administration/deploy/development/test_matrix_deploy.py
T
kevinveenbirkenbachandClaude Opus 4.8 16aa00d905 refactor(deploy-cli): split deploy.py into a per-responsibility package
One module per concern, mirroring the inventory/ subpackage layout:
run.py (single deploy pass + env forwarding SPOT), drill.py (recover
drill, host mode exempt, paths from CONTAINER_REPO_ROOT instead of a
hardcoded /opt/src/infinito), purge.py (inter-round cleanup) and
cli.py (arg parsing + round/pass loop, PASS 1/2 deduplicated).

Also extend the comment linter to flag bare string-expression
statements outside docstring position in Python: a triple-quoted
literal floating in a body is a comment in disguise and now runs
through the same validity rules; docstrings and PEP 224 attribute
docstrings stay allowed. Test narration comments moved into method
docstrings accordingly, and the design docs now link deploy/cli.py.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-16 05:20:54 +02:00

589 lines
21 KiB
Python

"""Unit tests for the deploy-side matrix iteration: each round deploys its own
variant-closure (``include``); between rounds the wrapper wipes the union
(``purge_set``).
deploy.handler reads the running container name strictly via
cli.administration.deploy.development.common.resolve_container (which is
sourced from scripts/meta/env/load.sh, the single SPOT for the formula).
That resolver is patched for the whole test module instead of duplicating
the formula or hard-coding INFINITO_CONTAINER in os.environ. The tests
below do not assert on the returned value; the sentinel is purely an
opaque fixture string.
"""
from __future__ import annotations
import argparse
import unittest
from pathlib import Path
from unittest.mock import MagicMock, patch
_RESOLVE_CONTAINER_PATCHER = patch(
"cli.administration.deploy.development.deploy.cli.resolve_container",
return_value="<unit-test fixture>",
)
_RESOLVE_CONTAINER_PATCHER.start()
from cli.administration.deploy.development.deploy import handler # noqa: E402
def _args(
*,
apps: list[str] | None = None,
variant: list[int] | None = None,
full_cycle: bool = False,
) -> argparse.Namespace:
"""Namespace fixture for handler(). `distro` is intentionally absent:
deploy.handler no longer consumes it (the --distro arg was retired in
favour of resolve_distro() reading INFINITO_DISTRO env strictly)."""
return argparse.Namespace(
inventory_dir="/srv/inv",
apps=None,
id=apps,
debug=False,
variant=variant,
full_cycle=full_cycle,
ansible_args=[],
)
def _entry(
round_index: int,
inv_dir: str,
round_variants: dict[str, int],
include: tuple[str, ...] | None = None,
purge_set: tuple[str, ...] | None = None,
) -> tuple[int, str, dict[str, int], tuple[str, ...], tuple[str, ...]]:
"""5-tuple plan entry. Defaults: include=round_variants.keys(), purge_set=include — pass purge_set explicitly when round closures differ."""
if include is None:
include = tuple(round_variants.keys())
if purge_set is None:
purge_set = include
return (round_index, inv_dir, round_variants, include, purge_set)
def _make_compose_mock() -> MagicMock:
compose = MagicMock()
compose.repo_root = Path("/tmp/infinito-nexus")
return compose
class TestHandlerMatrixDeploy(unittest.TestCase):
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_single_round_skips_matrix_loop(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
"""Single deploy against the unsuffixed folder, no cleanup."""
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv", {"web-app-jira": 0, "web-app-keycloak": 0}),
]
run_deploy_mock.return_value = 0
rc = handler(_args(apps=["web-app-jira", "web-app-keycloak"]))
self.assertEqual(rc, 0)
run_deploy_mock.assert_called_once()
self.assertEqual(run_deploy_mock.call_args.kwargs["inventory_dir"], "/srv/inv")
purge_mock.assert_not_called()
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_every_round_redeploys_full_include_after_purge(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
"""Variant 0 covers BOTH apps, variant 1 only exists for WordPress.
Each round starts from a clean host (the previous round's full
include is purged), so round 1 redeploys the full round-1 include,
Keycloak included even though it stays on variant 0, because the
round-0 baseline was just purged away. Purge runs once between
rounds with the FULL previous round include, not just
variant-changed apps."""
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv-0", {"web-app-wordpress": 0, "web-app-keycloak": 0}),
_entry(1, "/srv/inv-1", {"web-app-wordpress": 1, "web-app-keycloak": 0}),
]
run_deploy_mock.return_value = 0
rc = handler(_args(apps=["web-app-wordpress", "web-app-keycloak"]))
self.assertEqual(rc, 0)
self.assertEqual(run_deploy_mock.call_count, 2)
round_one_deploy_ids = run_deploy_mock.call_args_list[1].kwargs["deploy_ids"]
self.assertEqual(
sorted(round_one_deploy_ids),
["web-app-keycloak", "web-app-wordpress"],
)
purge_mock.assert_called_once()
self.assertEqual(
sorted(purge_mock.call_args.kwargs["app_ids"]),
["web-app-keycloak", "web-app-wordpress"],
)
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_two_round_plan_deploys_each_folder_in_order(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
"""Between rounds the FULL previous-round include is purged so
round 1 starts from a clean host, keycloak too, even though it
stays on variant 0."""
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv-0", {"web-app-multi": 0, "web-app-keycloak": 0}),
_entry(1, "/srv/inv-1", {"web-app-multi": 1, "web-app-keycloak": 0}),
]
run_deploy_mock.return_value = 0
rc = handler(_args(apps=["web-app-multi", "web-app-keycloak"]))
self.assertEqual(rc, 0)
self.assertEqual(run_deploy_mock.call_count, 2)
self.assertEqual(
[c.kwargs["inventory_dir"] for c in run_deploy_mock.call_args_list],
["/srv/inv-0", "/srv/inv-1"],
)
purge_mock.assert_called_once()
self.assertEqual(
sorted(purge_mock.call_args.kwargs["app_ids"]),
["web-app-keycloak", "web-app-multi"],
)
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_three_round_plan_redeploys_full_include_each_round(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
"""WordPress 2 variants, Discourse 3 variants, Keycloak 1 variant.
Each round starts from a clean host (full-include purge) and
therefore redeploys ITS OWN full include, keycloak too, even
though it has no later variants. Purge runs between rounds with
the FULL previous-round include."""
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(
0,
"/srv/inv-0",
{"web-app-wordpress": 0, "web-app-discourse": 0, "web-app-keycloak": 0},
),
_entry(
1,
"/srv/inv-1",
{"web-app-wordpress": 1, "web-app-discourse": 1, "web-app-keycloak": 0},
),
_entry(
2,
"/srv/inv-2",
{"web-app-wordpress": 0, "web-app-discourse": 2, "web-app-keycloak": 0},
),
]
run_deploy_mock.return_value = 0
rc = handler(
_args(
apps=[
"web-app-wordpress",
"web-app-discourse",
"web-app-keycloak",
]
)
)
self.assertEqual(rc, 0)
self.assertEqual(run_deploy_mock.call_count, 3)
full_include = ["web-app-discourse", "web-app-keycloak", "web-app-wordpress"]
per_round_deploy_ids = [
sorted(c.kwargs["deploy_ids"]) for c in run_deploy_mock.call_args_list
]
for round_index, deploy_ids in enumerate(per_round_deploy_ids):
self.assertEqual(
deploy_ids, full_include, f"round {round_index} deploy_ids drifted"
)
self.assertEqual(purge_mock.call_count, 2)
for call in purge_mock.call_args_list:
self.assertEqual(sorted(call.kwargs["app_ids"]), full_include)
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_round_transition_purges_union_when_variant_closures_differ(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
"""Round 1 must deploy only its own closure (no coturn), yet the
inter-round purge must wipe the union (coturn included)."""
make_compose_mock.return_value = _make_compose_mock()
union = ("web-app-nextcloud", "web-svc-coturn")
plan_mock.return_value = [
_entry(
0,
"/srv/inv-0",
{"web-app-nextcloud": 0},
include=("web-app-nextcloud", "web-svc-coturn"),
purge_set=union,
),
_entry(
1,
"/srv/inv-1",
{"web-app-nextcloud": 1},
include=("web-app-nextcloud",),
purge_set=union,
),
]
run_deploy_mock.return_value = 0
rc = handler(_args(apps=["web-app-nextcloud"]))
self.assertEqual(rc, 0)
self.assertEqual(run_deploy_mock.call_count, 2)
round_zero_deploy_ids = run_deploy_mock.call_args_list[0].kwargs["deploy_ids"]
round_one_deploy_ids = run_deploy_mock.call_args_list[1].kwargs["deploy_ids"]
self.assertEqual(
sorted(round_zero_deploy_ids),
["web-app-nextcloud", "web-svc-coturn"],
)
self.assertEqual(round_one_deploy_ids, ["web-app-nextcloud"])
purge_mock.assert_called_once()
self.assertEqual(
sorted(purge_mock.call_args.kwargs["app_ids"]),
["web-app-nextcloud", "web-svc-coturn"],
)
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_failure_in_round_one_aborts_before_round_two(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
"""Round 1 ran and failed, round 2 must NOT have been attempted."""
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv-0", {"web-app-multi": 0}),
_entry(1, "/srv/inv-1", {"web-app-multi": 1}),
]
run_deploy_mock.return_value = 17
rc = handler(_args(apps=["web-app-multi"]))
self.assertEqual(rc, 17)
run_deploy_mock.assert_called_once()
purge_mock.assert_not_called()
class TestHandlerVariantPin(unittest.TestCase):
"""`--variant <idx>` (or variant env-var) pins the deploy to one
specific round's folder, skipping inter-round cleanup. Use case:
redeploying one variant without iterating the whole matrix."""
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_variant_one_runs_only_that_round_no_cleanup(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
"""Only the picked round runs; no cleanup because there is no
previous round to diff against in single-round mode."""
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv-0", {"web-app-multi": 0}),
_entry(1, "/srv/inv-1", {"web-app-multi": 1}),
]
run_deploy_mock.return_value = 0
rc = handler(_args(apps=["web-app-multi"], variant=[1]))
self.assertEqual(rc, 0)
run_deploy_mock.assert_called_once()
self.assertEqual(
run_deploy_mock.call_args.kwargs["inventory_dir"], "/srv/inv-1"
)
purge_mock.assert_not_called()
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_variant_out_of_range_exits_with_clean_message(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
_purge_mock: MagicMock,
) -> None:
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv-0", {"web-app-multi": 0}),
_entry(1, "/srv/inv-1", {"web-app-multi": 1}),
]
with self.assertRaisesRegex(SystemExit, r"variants \[7\] out of range"):
handler(_args(apps=["web-app-multi"], variant=[7]))
run_deploy_mock.assert_not_called()
class TestHandlerFullCycle(unittest.TestCase):
"""`--full-cycle` runs an async re-deploy IMMEDIATELY after each
round's sync deploy (Pass 2 stays co-located with Pass 1 on the
same variant). Without `--full-cycle` only Pass 1 runs per round."""
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_full_cycle_runs_pass2_after_each_round(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
"""Two rounds, two passes each = 4 deploy calls, per-variant
interleave: round-0 sync, round-0 async, then round-1 sync,
round-1 async. Every call carries the zero-based VARIANT_INDEX so
consumers like the test-e2e-playwright role can namespace their
artifacts. Cleanup still runs once between rounds with the full
previous-round include."""
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv-0", {"web-app-multi": 0}),
_entry(1, "/srv/inv-1", {"web-app-multi": 1}),
]
run_deploy_mock.return_value = 0
rc = handler(_args(apps=["web-app-multi"], full_cycle=True))
self.assertEqual(rc, 0)
self.assertEqual(run_deploy_mock.call_count, 4)
sequence = [
(call.kwargs["inventory_dir"], call.kwargs.get("extra_ansible_vars"))
for call in run_deploy_mock.call_args_list
]
self.assertEqual(
sequence,
[
("/srv/inv-0", {"VARIANT_INDEX": 0}),
("/srv/inv-0", {"ASYNC_ENABLED": True, "VARIANT_INDEX": 0}),
("/srv/inv-1", {"VARIANT_INDEX": 1}),
("/srv/inv-1", {"ASYNC_ENABLED": True, "VARIANT_INDEX": 1}),
],
)
purge_mock.assert_called_once()
self.assertEqual(purge_mock.call_args.kwargs["app_ids"], ["web-app-multi"])
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_full_cycle_aborts_when_pass1_fails_skipping_pass2(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
_purge_mock: MagicMock,
) -> None:
"""PASS 1 of round 0 fails. PASS 2 of round 0 and the entire round
1 must be skipped to surface the failure cleanly."""
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv-0", {"web-app-multi": 0}),
_entry(1, "/srv/inv-1", {"web-app-multi": 1}),
]
run_deploy_mock.return_value = 11
rc = handler(_args(apps=["web-app-multi"], full_cycle=True))
self.assertEqual(rc, 11)
run_deploy_mock.assert_called_once()
@patch(
"cli.administration.deploy.development.deploy.cli._purge_app_entities",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli._run_deploy", autospec=True
)
@patch(
"cli.administration.deploy.development.deploy.cli.plan_dev_inventory_matrix",
autospec=True,
)
@patch(
"cli.administration.deploy.development.deploy.cli.make_compose", autospec=True
)
def test_full_cycle_with_variant_pin_runs_only_one_round_with_both_passes(
self,
make_compose_mock: MagicMock,
plan_mock: MagicMock,
run_deploy_mock: MagicMock,
purge_mock: MagicMock,
) -> None:
make_compose_mock.return_value = _make_compose_mock()
plan_mock.return_value = [
_entry(0, "/srv/inv-0", {"web-app-multi": 0}),
_entry(1, "/srv/inv-1", {"web-app-multi": 1}),
]
run_deploy_mock.return_value = 0
rc = handler(_args(apps=["web-app-multi"], variant=[1], full_cycle=True))
self.assertEqual(rc, 0)
self.assertEqual(run_deploy_mock.call_count, 2)
sequence = [
(call.kwargs["inventory_dir"], call.kwargs.get("extra_ansible_vars"))
for call in run_deploy_mock.call_args_list
]
self.assertEqual(
sequence,
[
("/srv/inv-1", {"VARIANT_INDEX": 1}),
("/srv/inv-1", {"ASYNC_ENABLED": True, "VARIANT_INDEX": 1}),
],
)
purge_mock.assert_not_called()
if __name__ == "__main__":
unittest.main()