From b8ed48612244a87675c1cfae6f830e4ef60cf989 Mon Sep 17 00:00:00 2001
From: Pedro Brochado <pedropsb95@gmail.com>
Date: Fri, 11 Oct 2024 17:56:20 -0300
Subject: [PATCH] Add html-snapshot testing with basic fixture

---
 src/pulp_docs/main.py                |  5 ++-
 src/pulp_docs/test_tools/snapshot.py | 46 +++++++++++++++++++++++++++
 tests/doctrees/pulpcore_only.toml    | 47 ++++++++++++++++++++++++++++
 tests/test_fixture_snapshot.py       | 10 ++++++
 4 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 src/pulp_docs/test_tools/snapshot.py
 create mode 100644 tests/doctrees/pulpcore_only.toml
 create mode 100644 tests/test_fixture_snapshot.py

diff --git a/src/pulp_docs/main.py b/src/pulp_docs/main.py
index 57e16c8..6413708 100644
--- a/src/pulp_docs/main.py
+++ b/src/pulp_docs/main.py
@@ -85,7 +85,10 @@ def serve(self, config: Config, dry_run: bool = False):
             return
         subprocess.run(cmd, env=env)
 
-    def build(self, config: Config, dry_run: bool = False):
+    def build(
+        self, config: Config, dry_run: bool = False, target: t.Optional[Path] = None
+    ):
+        # TODO: implement target
         # Process option to pass to command
         cmd = ["mkdocs", "build"]
 
diff --git a/src/pulp_docs/test_tools/snapshot.py b/src/pulp_docs/test_tools/snapshot.py
new file mode 100644
index 0000000..8ee52e2
--- /dev/null
+++ b/src/pulp_docs/test_tools/snapshot.py
@@ -0,0 +1,46 @@
+from pathlib import Path
+from pulp_docs.main import PulpDocs, Config
+
+
+def snapshot_fixture(fixture_dir: Path, repolist: Path, target: Path) -> Path:
+    """Builds snapshot of the fixture-docs using @fixture_dir and @repolist at @target.
+
+    The snapshot should be taken after someone carefully inspect the core elements of
+    the site looks as expected, like:
+    * Navigation display: nav items that should and shouldnt be there.
+    * Special pages behave as expected, like RestAPI, Changes and index pages.
+    * Regular pages exists (or dont exist) where expected inside plugins and sections.
+
+    The snapshot is not intended to provide a 1:1 comparision, but more of a structural
+    comparision, so at least we catch obivous structural regressions.
+
+    Params:
+        fixture_dir: A dir which should contain `{repository_name}/{repository_tree}`
+        repolist: A yaml file containing the aggregation config.
+        target: Dir where to write the build.
+
+    Returns:
+        The Path of the new snapshot. The dirname is commit hash at the moment of the
+        which snapshot.
+    """
+    # Guards to avoid surprises
+    if not fixture_dir.is_dir():
+        raise ValueError(f"'fixture_dir' should be a dir: {fixture_dir}")
+    if not list(fixture_dir.iterdir()):
+        raise ValueError(f"'fixture_dir' should NOT be empty.: {fixture_dir}")
+
+    if not target.is_dir():
+        raise ValueError(f"'fixture_dir' should be a dir: {target}")
+    if list(fixture_dir.iterdir()):
+        raise ValueError(f"'target' must be empty.: {target}")
+
+    if repolist.suffix not in (".yml", "yaml"):
+        raise ValueError(f"'repolist' must be a YAML file: {repolist.name}")
+
+    # TODO: test this.
+    config = Config()
+    config.repolist = repolist.absolute()
+    pulp_docs = PulpDocs(config)
+    pulp_docs.build(target=target)
+
+    return Path()
diff --git a/tests/doctrees/pulpcore_only.toml b/tests/doctrees/pulpcore_only.toml
new file mode 100644
index 0000000..80d2dfa
--- /dev/null
+++ b/tests/doctrees/pulpcore_only.toml
@@ -0,0 +1,47 @@
+################
+### PULPCORE ###
+################
+# Minimal setup with pulpcore only.
+
+	[[ pulpcore ]]
+
+path = 'pulpcore/CHANGES.md'
+data = '''
+# Changelog
+
+## x.y.z (YYYY-MM-DD)
+
+#### Features
+- feature-changes-check
+
+#### Bugfixes
+- bugfixes-changes-check
+'''
+
+	[[ pulpcore ]]
+
+path = 'pulpcore/index.md'
+data = '''
+# Welcome to Pulpcore
+
+pulpcore-index-check
+'''
+
+	[[ pulpcore ]]
+
+path = 'pulpcore/guides/guides1.md'
+data = '''
+# Guide1
+
+guide1-check
+'''
+
+	[[ pulpcore ]]
+
+path = 'pulpcore/guides/guides2.md'
+
+data = '''
+# Guide2
+
+guide2-check
+'''
diff --git a/tests/test_fixture_snapshot.py b/tests/test_fixture_snapshot.py
new file mode 100644
index 0000000..22b65a4
--- /dev/null
+++ b/tests/test_fixture_snapshot.py
@@ -0,0 +1,10 @@
+from pulp_docs.test_tools.snapshot import snapshot_fixture
+from pathlib import Path
+
+
+def test_snapshot_fixture(tmp_path):
+    """Test that using different fixture_dir or repolist the snapshot is different."""
+    fixture_dir = Path()
+    target = Path()
+    repolist = Path()
+    dirname = snapshot_fixture(fixture_dir, repolist, target)