edq-utils 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

edq/testing/cli.py

@@ -0,0 +1,253 @@
+"""
+Infrastructure for testing CLI tools using a JSON file which describes a test case,
+which is essentially an invocation of a CLI tool and the expected output.
+
+The test case file must be a `.txt` file that live in TEST_CASES_DIR.
+The file contains two parts (separated by a line with just TEST_CASE_SEP):
+the first part which is a JSON object (see below for available keys),
+and a second part which is the expected text output (stdout).
+For the keys of the JSON section, see the defaulted arguments to CLITestInfo.
+The options JSON will be splatted into CLITestInfo's constructor.
+
+The expected output or any argument can reference the test's current temp or data dirs with `__TEMP_DIR__()` or `__DATA_DIR__()`, respectively.
+An optional slash-separated path can be used as an argument to reference a path within those base directories.
+For example, `__DATA_DIR__(foo/bar.txt)` references `bar.txt` inside the `foo` directory inside the data directory.
+"""
+
+import contextlib
+import glob
+import io
+import os
+import re
+import sys
+import typing
+
+import edq.testing.asserts
+import edq.testing.unittest
+import edq.util.dirent
+import edq.util.json
+import edq.util.pyimport
+
+THIS_DIR: str = os.path.abspath(os.path.dirname(os.path.realpath(__file__)))
+BASE_TESTDATA_DIR: str = os.path.join(THIS_DIR, "testdata", "cli")
+TEST_CASES_DIR: str = os.path.join(BASE_TESTDATA_DIR, "tests")
+DATA_DIR: str = os.path.join(BASE_TESTDATA_DIR, "data")
+
+TEST_CASE_SEP: str = '---'
+DATA_DIR_ID: str = '__DATA_DIR__'
+TEMP_DIR_ID: str = '__TEMP_DIR__'
+REL_DIR_ID: str = '__REL_DIR__'
+
+DEFAULT_ASSERTION_FUNC_NAME: str = 'edq.testing.asserts.content_equals_normalize'
+
+BASE_TEMP_DIR_ATTR: str = '_edq_cli_base_test_dir'
+
+class CLITestInfo:
+    """ The required information to run a CLI test. """
+
+    def __init__(self,
+            test_name: str,
+            base_dir: str,
+            temp_dir: str,
+            cli: typing.Union[str, None] = None,
+            arguments: typing.Union[typing.List[str], None] = None,
+            error: bool = False,
+            platform_skip: typing.Union[str, None] = None,
+            stdout_assertion_func: typing.Union[str, None] = DEFAULT_ASSERTION_FUNC_NAME,
+            stderr_assertion_func: typing.Union[str, None] = None,
+            expected_stdout: str = '',
+            expected_stderr: str = '',
+            strip_error_output: bool = True,
+            **kwargs: typing.Any) -> None:
+        self.test_name: str = test_name
+        """ The name of this test. """
+
+        self.base_dir: str = base_dir
+        """ The base directory for this test (usually the dir the CLI test file lives. """
+
+        self.temp_dir: str = temp_dir
+        """ A temp directory that this test has access to. """
+
+        edq.util.dirent.mkdir(temp_dir)
+
+        if (cli is None):
+            raise ValueError("Missing CLI module.")
+
+        self.module_name: str = cli
+        """ The name of the module to invoke. """
+
+        self.module: typing.Any = edq.util.pyimport.import_name(self.module_name)
+        """ The module to invoke. """
+
+        if (arguments is None):
+            arguments = []
+
+        self.arguments: typing.List[str] = arguments
+        """ The CLI arguments. """
+
+        self.error: bool = error
+        """ Whether or not this test is expected to be an error (raise an exception). """
+
+        self.platform_skip: typing.Union[str, None] = platform_skip
+        """ If the current platform matches this regular expression, then the test will be skipped. """
+
+        self.stdout_assertion_func: typing.Union[edq.testing.asserts.StringComparisonAssertion, None] = None
+        """ The assertion func to compare the expected and actual stdout of the CLI. """
+
+        if (stdout_assertion_func is not None):
+            self.stdout_assertion_func = edq.util.pyimport.fetch(stdout_assertion_func)
+
+        self.stderr_assertion_func: typing.Union[edq.testing.asserts.StringComparisonAssertion, None] = None
+        """ The assertion func to compare the expected and actual stderr of the CLI. """
+
+        if (stderr_assertion_func is not None):
+            self.stderr_assertion_func = edq.util.pyimport.fetch(stderr_assertion_func)
+
+        self.expected_stdout: str = expected_stdout
+        """ The expected stdout. """
+
+        self.expected_stderr: str = expected_stderr
+        """ The expected stderr. """
+
+        if (error and strip_error_output):
+            self.expected_stdout = self.expected_stdout.strip()
+            self.expected_stderr = self.expected_stderr.strip()
+
+        # Make any path normalizations over the arguments and expected output.
+        self.expected_stdout = self._expand_paths(self.expected_stdout)
+        self.expected_stderr = self._expand_paths(self.expected_stderr)
+        for (i, argument) in enumerate(self.arguments):
+            self.arguments[i] = self._expand_paths(argument)
+
+    def _expand_paths(self, text: str) -> str:
+        """
+        Expand path replacements in testing text.
+        This allows for consistent paths (even absolute paths) in the test text.
+        """
+
+        replacements = [
+            (DATA_DIR_ID, DATA_DIR),
+            (TEMP_DIR_ID, self.temp_dir),
+            (REL_DIR_ID, self.base_dir),
+        ]
+
+        for (key, target_dir) in replacements:
+            text = replace_path_pattern(text, key, target_dir)
+
+        return text
+
+    @staticmethod
+    def load_path(path: str, test_name: str, base_temp_dir: str) -> 'CLITestInfo':
+        """ Load a CLI test file and extract the test info. """
+
+        options, expected_stdout = read_test_file(path)
+
+        options['expected_stdout'] = expected_stdout
+
+        base_dir = os.path.dirname(os.path.abspath(path))
+        temp_dir = os.path.join(base_temp_dir, test_name)
+
+        return CLITestInfo(test_name, base_dir, temp_dir, **options)
+
+def read_test_file(path: str) -> typing.Tuple[typing.Dict[str, typing.Any], str]:
+    """ Read a test case file and split the output into JSON data and text. """
+
+    json_lines: typing.List[str] = []
+    output_lines: typing.List[str] = []
+
+    text = edq.util.dirent.read_file(path, strip = False)
+
+    accumulator = json_lines
+    for line in text.split("\n"):
+        if (line.strip() == TEST_CASE_SEP):
+            accumulator = output_lines
+            continue
+
+        accumulator.append(line)
+
+    options = edq.util.json.loads(''.join(json_lines))
+    output = "\n".join(output_lines)
+
+    return options, output
+
+def replace_path_pattern(text: str, key: str, target_dir: str) -> str:
+    """ Make any test replacement inside the given string. """
+
+    match = re.search(rf'{key}\(([^)]*)\)', text)
+    if (match is not None):
+        filename = match.group(1)
+
+        # Normalize any path separators.
+        filename = os.path.join(*filename.split('/'))
+
+        if (filename == ''):
+            path = target_dir
+        else:
+            path = os.path.join(target_dir, filename)
+
+        text = text.replace(match.group(0), path)
+
+    return text
+
+def _get_test_method(test_name: str, path: str) -> typing.Callable:
+    """ Get a test method that represents the test case at the given path. """
+
+    def __method(self: edq.testing.unittest.BaseTest) -> None:
+        test_info = CLITestInfo.load_path(path, test_name, getattr(self, BASE_TEMP_DIR_ATTR))
+
+        if ((test_info.platform_skip is not None) and re.search(test_info.platform_skip, sys.platform)):
+            self.skipTest(f"Test is not available on {sys.platform}.")
+
+        old_args = sys.argv
+        sys.argv = [test_info.module.__file__] + test_info.arguments
+
+        try:
+            with contextlib.redirect_stdout(io.StringIO()) as stdout_output:
+                with contextlib.redirect_stderr(io.StringIO()) as stderr_output:
+                    test_info.module.main()
+
+            stdout_text = stdout_output.getvalue()
+            stderr_text = stderr_output.getvalue()
+
+            if (test_info.error):
+                self.fail(f"No error was not raised when one was expected ('{str(test_info.expected_stdout)}').")
+        except BaseException as ex:
+            if (not test_info.error):
+                raise ex
+
+            stdout_text = self.format_error_string(ex)
+
+            stderr_text = ''
+            if (isinstance(ex, SystemExit) and (ex.__context__ is not None)):
+                stderr_text = self.format_error_string(ex.__context__)
+        finally:
+            sys.argv = old_args
+
+        if (test_info.stdout_assertion_func is not None):
+            test_info.stdout_assertion_func(self, test_info.expected_stdout, stdout_text)
+
+        if (test_info.stderr_assertion_func is not None):
+            test_info.stderr_assertion_func(self, test_info.expected_stderr, stderr_text)
+
+    return __method
+
+def add_test_paths(target_class: type, paths: typing.List[str]) -> None:
+    """ Add tests from the given test files. """
+
+    # Attach a temp directory to the testing class so all tests can share a common base temp dir.
+    if (not hasattr(target_class, BASE_TEMP_DIR_ATTR)):
+        setattr(target_class, BASE_TEMP_DIR_ATTR, edq.util.dirent.get_temp_path('edq_cli_test_'))
+
+    for path in sorted(paths):
+        test_name = 'test_cli__' + os.path.splitext(os.path.basename(path))[0]
+
+        try:
+            setattr(target_class, test_name, _get_test_method(test_name, path))
+        except Exception as ex:
+            raise ValueError(f"Failed to parse test case '{path}'.") from ex
+
+def discover_test_cases(target_class: type) -> None:
+    """ Look in the text cases directory for any test cases and add them as test methods to the test class. """
+
+    paths = list(sorted(glob.glob(os.path.join(TEST_CASES_DIR, "**", "*.txt"), recursive = True)))
+    add_test_paths(target_class, paths)

edq/testing/cli_test.py

@@ -0,0 +1,8 @@
+import edq.testing.cli
+import edq.testing.unittest
+
+class CLITest(edq.testing.unittest.BaseTest):
+    """ Test CLI invocations. """
+
+# Populate CLITest with all the test methods.
+edq.testing.cli.discover_test_cases(CLITest)

edq/testing/run.py

@@ -11,10 +11,6 @@ import sys
 import typing
 import unittest
 
-THIS_DIR: str = os.path.join(os.path.dirname(os.path.realpath(__file__)))
-BASE_PACKAGE_DIR: str = os.path.join(THIS_DIR, '..')
-PROJECT_ROOT_DIR: str = os.path.join(BASE_PACKAGE_DIR, '..')
-
 DEFAULT_TEST_FILENAME_PATTERN: str = '*_test.py'
 
 def _collect_tests(suite: typing.Union[unittest.TestCase, unittest.suite.TestSuite]) -> typing.List[unittest.TestCase]:
@@ -41,13 +37,22 @@ def run(args: argparse.Namespace) -> int:
     Will raise if tests fail to load (e.g. syntax errors) and a suggested exit code otherwise.
     """
 
-    # Start in the project's root and add it in the path.
-    os.chdir(PROJECT_ROOT_DIR)
-    sys.path.append(PROJECT_ROOT_DIR)
+    if (args.work_dir is not None):
+        os.chdir(args.work_dir)
+
+    if (args.path_additions is not None):
+        for path in args.path_additions:
+            sys.path.append(path)
+
+    if (args.test_dirs is None):
+        args.test_dirs = ['.']
 
     runner = unittest.TextTestRunner(verbosity = 3)
-    discovered_suite = unittest.TestLoader().discover(BASE_PACKAGE_DIR, pattern = args.filename_pattern)
-    test_cases = _collect_tests(discovered_suite)
+    test_cases = []
+
+    for test_dir in args.test_dirs:
+        discovered_suite = unittest.TestLoader().discover(test_dir, pattern = args.filename_pattern)
+        test_cases += _collect_tests(discovered_suite)
 
     tests = unittest.suite.TestSuite()
 
@@ -64,27 +69,43 @@ def run(args: argparse.Namespace) -> int:
     faults = len(result.errors) + len(result.failures)
 
     if (not result.wasSuccessful()):
-        # This value will be used as an exit status, so don't larger than a byte.
+        # This value will be used as an exit status, so it should not be larger than a byte.
         # (Some higher values are used specially, so just keep it at a round number.)
         return max(1, min(faults, 100))
 
     return 0
 
 def main() -> int:
+    """ Parse the CLI arguments and run tests. """
+
     args = _get_parser().parse_args()
     return run(args)
 
 def _get_parser() -> argparse.ArgumentParser:
+    """ Build a parser for CLI arguments. """
+
     parser = argparse.ArgumentParser(description = 'Run unit tests discovered in this project.')
 
-    parser.add_argument('pattern',
-        action = 'store', type = str, default = None, nargs = '?',
-        help = 'If supplied, only tests with names matching this pattern will be run. This pattern is used directly in re.search().')
+    parser.add_argument('--work-dir', dest = 'work_dir',
+        action = 'store', type = str, default = os.getcwd(),
+        help = 'Set the working directory when running tests, defaults to the current working directory (%(default)s).')
+
+    parser.add_argument('--tests-dir', dest = 'test_dirs',
+        action = 'append',
+        help = 'Discover tests from these directories. Defaults to the current directory.')
+
+    parser.add_argument('--add-path', dest = 'path_additions',
+        action = 'append',
+        help = 'If supplied, add this path the sys.path before running tests.')
 
     parser.add_argument('--filename-pattern', dest = 'filename_pattern',
         action = 'store', type = str, default = DEFAULT_TEST_FILENAME_PATTERN,
         help = 'The pattern to use to find test files (default: %(default)s).')
 
+    parser.add_argument('pattern',
+        action = 'store', type = str, default = None, nargs = '?',
+        help = 'If supplied, only tests with names matching this pattern will be run. This pattern is used directly in re.search().')
+
     return parser
 
 if __name__ == '__main__':

edq/testing/testdata/cli/tests/version_base.txt

@@ -0,0 +1,6 @@
+{
+    "cli": "edq.cli.version",
+    "arguments": [],
+}
+---
+<VERSION>

edq/testing/unittest.py

@@ -1,4 +1,3 @@
-import json
 import typing
 import unittest
 
@@ -15,13 +14,21 @@ class BaseTest(unittest.TestCase):
     maxDiff = None
     """ Don't limit the size of diffs. """
 
-    def assertJSONDictEqual(self, a: dict, b: dict) -> None:
+    def assertJSONDictEqual(self, a: typing.Dict[str, typing.Any], b: typing.Dict[str, typing.Any]) -> None:  # pylint: disable=invalid-name
+        """
+        Call assertDictEqual(), but supply a message containing the full JSON representation of the arguments.
+        """
+
         a_json = edq.util.json.dumps(a, indent = 4)
         b_json = edq.util.json.dumps(b, indent = 4)
 
         super().assertDictEqual(a, b, FORMAT_STR % (a_json, b_json))
 
-    def assertJSONListEqual(self, a: list, b: list) -> None:
+    def assertJSONListEqual(self, a: typing.List[typing.Any], b: typing.List[typing.Any]) -> None:  # pylint: disable=invalid-name
+        """
+        Call assertListEqual(), but supply a message containing the full JSON representation of the arguments.
+        """
+
         a_json = edq.util.json.dumps(a, indent = 4)
         b_json = edq.util.json.dumps(b, indent = 4)
 

edq/util/__init__.py

@@ -0,0 +1,3 @@
+"""
+Low-level utilities.
+"""

edq/util/dirent.py

@@ -13,6 +13,7 @@ import atexit
 import os
 import shutil
 import tempfile
+import typing
 import uuid
 
 DEFAULT_ENCODING: str = 'utf-8'
@@ -114,7 +115,7 @@ def remove(path: str) -> None:
     else:
         raise ValueError(f"Unknown type of dirent: '{path}'.")
 
-def same(a: str, b: str):
+def same(a: str, b: str) -> bool:
     """
     Check if two paths represent the same dirent.
     If either (or both) paths do not exist, false will be returned.
@@ -247,10 +248,10 @@ def read_file(raw_path: str, strip: bool = True, encoding: str = DEFAULT_ENCODIN
     return contents
 
 def write_file(
-        raw_path: str, contents: str,
+        raw_path: str, contents: typing.Union[str, None],
         strip: bool = True, newline: bool = True,
         encoding: str = DEFAULT_ENCODING,
-        no_clobber = False) -> None:
+        no_clobber: bool = False) -> None:
     """
     Write the contents of a file.
     If clobbering, any existing dirent will be removed before write.
@@ -276,6 +277,39 @@ def write_file(
     with open(path, 'w', encoding = encoding) as file:
         file.write(contents)
 
+def read_file_bytes(raw_path: str) -> bytes:
+    """ Read the contents of a file as bytes. """
+
+    path = os.path.abspath(raw_path)
+
+    if (not exists(path)):
+        raise ValueError(f"Source of read bytes does not exist: '{raw_path}'.")
+
+    with open(path, 'rb') as file:
+        return file.read()
+
+def write_file_bytes(
+        raw_path: str, contents: typing.Union[bytes, None],
+        no_clobber: bool = False) -> None:
+    """
+    Write the contents of a file as bytes.
+    If clobbering, any existing dirent will be removed before write.
+    """
+
+    path = os.path.abspath(raw_path)
+
+    if (exists(path)):
+        if (no_clobber):
+            raise ValueError(f"Destination of write bytes already exists: '{raw_path}'.")
+
+        remove(path)
+
+    if (contents is None):
+        contents = b''
+
+    with open(path, 'wb') as file:
+        file.write(contents)
+
 def contains_path(parent: str, child: str) -> bool:
     """
     Check if the parent path contains the child path.

edq/util/dirent_test.py

@@ -92,6 +92,124 @@ class TestDirent(edq.testing.unittest.BaseTest):
                 actual = edq.util.dirent.contains_path(parent, child)
                 self.assertEqual(expected, actual)
 
+    def test_read_write_file_bytes_base(self):
+        """ Test reading and writing a file as bytes. """
+
+        # [(path, write kwargs, read kwargs, write contents, expected contents, error substring), ...]
+        # All conent should be strings that will be encoded.
+        test_cases = [
+            # Base
+            (
+                "test.txt",
+                {},
+                {},
+                "test",
+                "test",
+                None,
+            ),
+
+            # Empty Write
+            (
+                "test.txt",
+                {},
+                {},
+                "",
+                "",
+                None,
+            ),
+
+            # None Write
+            (
+                "test.txt",
+                {},
+                {},
+                None,
+                "",
+                None,
+            ),
+
+            # Clobber
+            (
+                "a.txt",
+                {},
+                {},
+                "test",
+                "test",
+                None,
+            ),
+            (
+                "dir_1",
+                {},
+                {},
+                "test",
+                "test",
+                None,
+            ),
+            (
+                "symlink_a.txt",
+                {},
+                {},
+                "test",
+                "test",
+                None,
+            ),
+
+            # No Clobber
+            (
+                "a.txt",
+                {'no_clobber': True},
+                {},
+                "test",
+                "test",
+                'already exists',
+            ),
+            (
+                "dir_1",
+                {'no_clobber': True},
+                {},
+                "test",
+                "test",
+                'already exists',
+            ),
+            (
+                "symlink_a.txt",
+                {'no_clobber': True},
+                {},
+                "test",
+                "test",
+                'already exists',
+            ),
+        ]
+
+        for (i, test_case) in enumerate(test_cases):
+            (path, write_options, read_options, write_contents, expected_contents, error_substring) = test_case
+
+            with self.subTest(msg = f"Case {i} ('{path}'):"):
+                temp_dir = self._prep_temp_dir()
+                path = os.path.join(temp_dir, path)
+
+                if (write_contents is not None):
+                    write_contents = bytes(write_contents, edq.util.dirent.DEFAULT_ENCODING)
+
+                expected_contents = bytes(expected_contents, edq.util.dirent.DEFAULT_ENCODING)
+
+                try:
+                    edq.util.dirent.write_file_bytes(path, write_contents, **write_options)
+                    actual_contents = edq.util.dirent.read_file_bytes(path, **read_options)
+                except Exception as ex:
+                    error_string = self.format_error_string(ex)
+                    if (error_substring is None):
+                        self.fail(f"Unexpected error: '{error_string}'.")
+
+                    self.assertIn(error_substring, error_string, 'Error is not as expected.')
+
+                    continue
+
+                if (error_substring is not None):
+                    self.fail(f"Did not get expected error: '{error_substring}'.")
+
+                self.assertEqual(expected_contents, actual_contents)
+
     def test_read_write_file_base(self):
         """ Test reading and writing a file. """
 
@@ -157,7 +275,7 @@ class TestDirent(edq.testing.unittest.BaseTest):
                 None,
             ),
 
-            # None
+            # None Write
             (
                 "test.txt",
                 {'newline': False},
@@ -225,7 +343,6 @@ class TestDirent(edq.testing.unittest.BaseTest):
 
             with self.subTest(msg = f"Case {i} ('{path}'):"):
                 temp_dir = self._prep_temp_dir()
-
                 path = os.path.join(temp_dir, path)
 
                 try:
@@ -243,7 +360,7 @@ class TestDirent(edq.testing.unittest.BaseTest):
                 if (error_substring is not None):
                     self.fail(f"Did not get expected error: '{error_substring}'.")
 
-            self.assertEqual(expected_contents, actual_contents)
+                self.assertEqual(expected_contents, actual_contents)
 
     def test_copy_contents_base(self):
         """