Create basic tests covering excavation & output generation for example.

Make the minimal set of changes such that we are able to trigger the
excavation to a known directory of the in-tree example file. Check
that the expected HTML files were written for this known excavation
and assert some basic properties of the excavated arifacts.

The commit includes reworking of run_example wherein its excavation is
declared as a class and its core logic separated out into a run file.
This is done both to allow the tests to easily make use of the logic
and as groundwork for subsequent work to provide a unified entry point.

Author: alexjeffburke

.gitignore

@@ -9,3 +9,4 @@ docs/_build/
 # Temporary files
 _.*
 _autoarchaologist/
+tests/_scratch/

run.py

@@ -0,0 +1,48 @@
+import argparse
+import os
+import sys
+
+from autoarchaeologist.base.excavation import Excavation as ExcavationBase
+
+def parse_arguments(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-d", "--dir", default="/tmp/_autoarchaologist")
+    parser.add_argument('filename')
+
+    return parser.parse_args(args=argv)
+
+def process_arguments(args):
+    if args.dir == ".":
+        args.dir = os.path.join(os.getcwd(), "_autoarchaologist")
+    if args.filename is not None:
+        args.filename = os.path.abspath(args.filename)
+    else:
+        raise ValueError()
+
+    return args
+
+def perform_excavation(args, action_tuple):
+    match action_tuple:
+        case "excavator", Excavation:
+            assert issubclass(Excavation, ExcavationBase)
+            ctx = Excavation(html_dir=args.dir)
+        case action, _:
+            raise NotImplementedError(f"action: {action}")
+
+    ff = ctx.add_file_artifact(args.filename)
+
+    ctx.start_examination()
+
+    return ctx
+
+if __name__ == "__main__":
+    args = process_arguments(parse_arguments())
+
+    try:
+        os.mkdir(args.dir)
+    except FileExistsError:
+        pass
+
+    ctx = perform_excavation(args, ("none", None))
+    ctx.produce_html()
+    print("Now point your browser at", ctx.filename_for(ctx).link)

run_example.py

@@ -1,43 +1,38 @@
-
-import argparse
 import os
-import sys
-
-import autoarchaeologist
+from run import process_arguments, perform_excavation
+from types import SimpleNamespace
 
+from autoarchaeologist.base.excavation import Excavation
 from autoarchaeologist.generic.bigdigits import BigDigits
 from autoarchaeologist.generic.samesame import SameSame
 from autoarchaeologist.data_general.absbin import AbsBin
 from autoarchaeologist.data_general.papertapechecksum import DGC_PaperTapeCheckSum
 
-def parse_arguments(argv=None):
-    parser = argparse.ArgumentParser()
-    parser.add_argument("-d", "--dir", default="/tmp/_autoarchaologist")
+EXAMPLES_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "examples")
 
-    args = parser.parse_args(args=argv)
-    if args.dir == ".":
-        args.dir = os.path.join(os.getcwd(), "_autoarchaologist")
-    return args
+class ExampleExcavation(Excavation):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
 
-if __name__ == "__main__":
-    args = parse_arguments()
+        self.add_examiner(BigDigits)
+        self.add_examiner(AbsBin)
+        self.add_examiner(DGC_PaperTapeCheckSum)
+        self.add_examiner(SameSame)
+
+def process_example(*, html_dir):
+    example_arguments = SimpleNamespace()
+    example_arguments.dir = html_dir
+    example_arguments.filename = os.path.join(EXAMPLES_DIR, "30001393.bin")
+    args = process_arguments(example_arguments)
 
     try:
         os.mkdir(args.dir)
     except FileExistsError:
         pass
 
-    ctx = autoarchaeologist.Excavation(html_dir=args.dir)
-
-    ctx.add_examiner(BigDigits)
-    ctx.add_examiner(AbsBin)
-    ctx.add_examiner(DGC_PaperTapeCheckSum)
-    ctx.add_examiner(SameSame)
-
-    ff = ctx.add_file_artifact("examples/30001393.bin")
-
-    ctx.start_examination()
+    return perform_excavation(args, ("excavator", ExampleExcavation))
 
+if __name__ == "__main__":
+    ctx = process_example(html_dir=".")
     ctx.produce_html()
-
     print("Now point your browser at", ctx.filename_for(ctx).link)

tests/__init__.py

@@ -0,0 +1,103 @@
+import importlib
+import os
+import shutil
+import sys
+import unittest
+
+TESTS_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = os.path.normpath(os.path.join(TESTS_DIR, ".."))
+
+# run_example is technically outside the package so force its import
+sys.path.append(ROOT_DIR)
+from run_example import process_example
+from autoarchaeologist.base.artifact import ArtifactBase, ArtifactStream
+sys.path.remove(ROOT_DIR)
+
+SCRATCH_DIR = os.path.join(TESTS_DIR, "_scratch")
+
+def scratch_path(path):
+    return os.path.join(SCRATCH_DIR, path)
+
+class RunExampleBasicHtml(unittest.TestCase):
+    """
+    Ensure run_example produces expected HTML files for the example input.
+    """
+
+    DIR_TREE = None
+
+    @classmethod
+    def setUpClass(cls):
+        shutil.rmtree(SCRATCH_DIR)
+        os.makedirs(SCRATCH_DIR, exist_ok=True)
+        ctx = process_example(html_dir=SCRATCH_DIR)
+        ctx.produce_html()
+        cls.DIR_TREE = list(os.walk(SCRATCH_DIR))
+
+    def toplevel(self):
+        return self.__class__.DIR_TREE[0]
+
+    def toplevel_dirnames(self):
+        _, dirs, __ = self.toplevel()
+        dirs.sort()
+        return dirs
+
+    def toplevel_filenames(self):
+        _, __, filenames = self.toplevel()
+        return filenames
+
+    def test_produces_top_level_index(self):
+        toplevel_filenames = self.toplevel_filenames()
+        self.assertTrue("index.html" in toplevel_filenames)
+        self.assertTrue("index.css" in toplevel_filenames)
+
+    def test_produces_digest_directories(self):
+        toplevel_dirnames = self.toplevel_dirnames()
+        self.assertEqual(toplevel_dirnames, ['08', '79', 'fa'])
+
+class RunExampleBasicArtifacts(unittest.TestCase):
+    """
+    Ensure run_example excavates the expected artifacts for the example input.
+    """
+
+    CTX = None
+
+    @classmethod
+    def setUpClass(cls):
+        cls.CTX = process_example(html_dir=SCRATCH_DIR)
+
+    def assertArtifactIsChild(self, artifact, parent):
+        assert issubclass(artifact.__class__, ArtifactBase)
+        self.assertEqual(list(artifact.parents), [parent])
+
+    def excavation(self):
+        return self.__class__.CTX
+
+    def test_excavated_three_total_artifacts(self):
+        arfifact_hash_keys = list(self.excavation().hashes.keys())
+        self.assertEqual(len(arfifact_hash_keys), 3)
+
+    def test_excavated_one_top_level_artifact(self):
+        excavatoin_child_count = len(self.excavation().children)
+        self.assertEqual(excavatoin_child_count, 1)
+
+    def test_produces_top_level_artifact(self):
+        excavation = self.excavation()
+        artifact = self.excavation().children[0]
+        self.assertIsInstance(artifact, ArtifactStream)
+        self.assertEqual(artifact.digest, '083a3d5e3098aec38ee5d9bc9f9880d3026e120ff8f058782d49ee3ccafd2a6c')
+
+    def test_produces_top_level_artifact_whose_parent_is_excavation(self):
+        artifact = self.excavation().children[0]
+        self.assertArtifactIsChild(artifact, self.excavation())
+
+    def test_produces_two_children_of_the_top_level(self):
+        artifact = self.excavation().children[0]
+        artifact_children = sorted(artifact.children, key=lambda a: a.digest)
+        self.assertEqual(len(artifact_children), 2)
+        self.assertTrue(artifact_children[0].digest.startswith('79'))
+        self.assertArtifactIsChild(artifact_children[0], artifact)
+        self.assertTrue(artifact_children[1].digest.startswith('fa'))
+        self.assertArtifactIsChild(artifact_children[1], artifact)
+
+if __name__ == '__main__':
+    unittest.main()