Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Exercise backup safety and diagnostic recipes on docs-only changes

pulse-triage[bot]51a30f71d3fb
diff --git a/.github/workflows/public-docs.yml b/.github/workflows/public-docs.yml
index e97be31dff..cd8e4a6ec8 100644
--- a/.github/workflows/public-docs.yml
+++ b/.github/workflows/public-docs.yml
@@ -10,6 +10,14 @@ on:
- "scripts/check_public_docs.py"
- "scripts/check_docs_mirror.py"
- "scripts/readme_entrypoints_test.py"
+ - "scripts/tests/run.sh"
+ - "scripts/tests/test_public_docs_workflow.py"
+ - "scripts/tests/test_pve_backup_troubleshooting_docs.py"
+ - "scripts/tests/test_vm_disk_diagnostics.py"
+ - "scripts/tests/test_memory_troubleshooting_docs.py"
+ - "scripts/tests/test_performance_troubleshooting_docs.py"
+ - "scripts/tests/test_troubleshooting_logs.py"
+ - "scripts/test-vm-disk.sh"
- ".github/workflows/public-docs.yml"
push:
branches:
@@ -22,6 +30,14 @@ on:
- "scripts/check_public_docs.py"
- "scripts/check_docs_mirror.py"
- "scripts/readme_entrypoints_test.py"
+ - "scripts/tests/run.sh"
+ - "scripts/tests/test_public_docs_workflow.py"
+ - "scripts/tests/test_pve_backup_troubleshooting_docs.py"
+ - "scripts/tests/test_vm_disk_diagnostics.py"
+ - "scripts/tests/test_memory_troubleshooting_docs.py"
+ - "scripts/tests/test_performance_troubleshooting_docs.py"
+ - "scripts/tests/test_troubleshooting_logs.py"
+ - "scripts/test-vm-disk.sh"
- ".github/workflows/public-docs.yml"
permissions:
@@ -49,3 +65,18 @@ jobs:
- name: Check shipped docs mirror sync
run: python3 scripts/check_docs_mirror.py
+
+ - name: Check documentation safety workflow contract
+ run: python3 scripts/tests/test_public_docs_workflow.py
+
+ # Build and Test intentionally skips its smoke suite for docs-only
+ # changes. Exercise the existing safety guidance and copied recipes here
+ # too, without installing frontend/Go dependencies or calling providers.
+ - name: Exercise backup safety and diagnostic recipes
+ run: |
+ scripts/tests/run.sh \
+ test_pve_backup_troubleshooting_docs.py \
+ test_vm_disk_diagnostics.py \
+ test_memory_troubleshooting_docs.py \
+ test_performance_troubleshooting_docs.py \
+ test_troubleshooting_logs.py
diff --git a/scripts/tests/test_public_docs_workflow.py b/scripts/tests/test_public_docs_workflow.py
new file mode 100644
index 0000000000..b0980d5516
--- /dev/null
+++ b/scripts/tests/test_public_docs_workflow.py
@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Docs-only CI must exercise safety guidance, not just its Markdown shape.
+
+Read the canonical block-YAML surface (also checked by workflow trust), then
+execute its actual smoke command with disposable test adapters. No provider,
+host service, backup or guest-agent operation is used.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import re
+import shlex
+import shutil
+import subprocess
+import tempfile
+import textwrap
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+WORKFLOW = ROOT / ".github/workflows/public-docs.yml"
+SAFETY_STEP = "Exercise backup safety and diagnostic recipes"
+TESTS = (
+ "test_pve_backup_troubleshooting_docs.py",
+ "test_vm_disk_diagnostics.py",
+ "test_memory_troubleshooting_docs.py",
+ "test_performance_troubleshooting_docs.py",
+ "test_troubleshooting_logs.py",
+)
+
+
+def step_body(source: str, name: str) -> str:
+ marker = f" - name: {name}\n"
+ if source.count(marker) != 1:
+ raise AssertionError(f"expected exactly one {name} step")
+ return source.split(marker, 1)[1].split("\n - name:", 1)[0]
+
+
+def safety_command(source: str) -> str:
+ body = step_body(source, SAFETY_STEP)
+ marker = " run: |\n"
+ if body.count(marker) != 1:
+ raise AssertionError("expected one literal safety command")
+ return textwrap.dedent(body.split(marker, 1)[1]).strip()
+
+
+class PublicDocsWorkflowTest(unittest.TestCase):
+ def setUp(self):
+ self.source = WORKFLOW.read_text(encoding="utf-8")
+
+ def test_both_events_cover_docs_checks_runner_and_helper(self):
+ triggers = self.source.split("\non:\n", 1)[1].split("\npermissions:", 1)[0]
+ required = {
+ "*.md", "docs/**", "frontend-modern/public/docs/**",
+ "scripts/check_public_docs.py", "scripts/check_docs_mirror.py",
+ "scripts/readme_entrypoints_test.py", "scripts/tests/run.sh",
+ "scripts/tests/test_public_docs_workflow.py", "scripts/test-vm-disk.sh",
+ ".github/workflows/public-docs.yml",
+ *(f"scripts/tests/{name}" for name in TESTS),
+ }
+ for event in ("pull_request", "push"):
+ with self.subTest(event=event):
+ block = triggers.split(f" {event}:\n", 1)[1]
+ block = re.split(r"\n [a-z_]+:\n", block, maxsplit=1)[0]
+ paths = re.findall(r'^ - "([^"]+)"$', block, re.MULTILINE)
+ self.assertTrue(required.issubset(paths), required.difference(paths))
+ self.assertEqual(len(paths), len(set(paths)))
+ self.assertIn(" push:\n branches:\n - main\n", triggers)
+
+ def test_exact_existing_suites_run_without_dependency_setup(self):
+ command = safety_command(self.source).replace("\\\n", " ")
+ self.assertEqual(shlex.split(command), ["scripts/tests/run.sh", *TESTS])
+ for name in TESTS:
+ self.assertTrue((ROOT / "scripts/tests" / name).is_file())
+ self.assertNotIn("actions/setup-", self.source)
+ self.assertNotRegex(self.source, r"\b(?:npm|pip|go) (?:ci|install|build|test)\b")
+
+ def test_existing_document_admissions_are_preserved(self):
+ for name, command in (
+ ("Validate public documentation", "python3 scripts/check_public_docs.py"),
+ ("Check getting-started safety and current plans", "python3 scripts/readme_entrypoints_test.py"),
+ ("Check shipped docs mirror sync", "python3 scripts/check_docs_mirror.py"),
+ ("Check documentation safety workflow contract", "python3 scripts/tests/test_public_docs_workflow.py"),
+ ):
+ with self.subTest(step=name):
+ self.assertIn(f" run: {command}\n", step_body(self.source, name))
+
+ def test_safety_checks_cannot_be_conditionally_skipped_or_softened(self):
+ self.assertNotRegex(self.source, r"(?m)^\s*(?:if|continue-on-error):")
+ self.assertIn("permissions:\n contents: read\n", self.source)
+ self.assertIn(" persist-credentials: false\n", self.source)
+ self.assertIn(" timeout-minutes: 10\n", self.source)
+
+ def run_adapters(self, failing: str = ""):
+ with tempfile.TemporaryDirectory() as temporary:
+ root = Path(temporary)
+ tests = root / "scripts/tests"
+ tests.mkdir(parents=True)
+ shutil.copyfile(ROOT / "scripts/tests/run.sh", tests / "run.sh")
+ (tests / "run.sh").chmod(0o700)
+ for name in TESTS:
+ (tests / name).write_text(
+ "import os\nfrom pathlib import Path\n"
+ f"with Path(os.environ['CALLS']).open('a') as log: log.write({name!r} + '\\n')\n"
+ f"raise SystemExit({1 if name == failing else 0})\n",
+ encoding="utf-8",
+ )
+ calls = root / "calls"
+ result = subprocess.run(
+ ["bash", "-e", "-o", "pipefail", "-c", safety_command(self.source)],
+ cwd=root, env=dict(os.environ, CALLS=str(calls)),
+ text=True, capture_output=True, timeout=15,
+ )
+ return result, calls.read_text().splitlines()
+
+ def test_actual_workflow_command_runs_every_suite(self):
+ result, calls = self.run_adapters()
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertEqual(calls, list(TESTS))
+ self.assertIn("Summary: 5/5 passed", result.stdout)
+
+ def test_each_failed_suite_is_a_failed_workflow_command(self):
+ for failing in TESTS:
+ with self.subTest(failing=failing):
+ result, calls = self.run_adapters(failing)
+ self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertEqual(calls, list(TESTS))
+ self.assertIn("Summary: 4/5 passed", result.stdout)
+ self.assertIn("Failures: 1", result.stdout)
+
+
+if __name__ == "__main__":
+ unittest.main()