Merge pull request #110 from LUMC/release_1.4.0

Release 1.4.0

Author: rhpvorderman

HISTORY.rst

@@ -7,6 +7,15 @@ Changelog
 .. This document is user facing. Please word the changes in such a way
 .. that users understand how the changes affect the new version.
 
+version 1.4.0
+---------------------------
++ Usage of the ``name`` keyword argument in workflow marks is now deprecated.
+  Using this will crash the plugin with a DeprecationWarning.
++ Update minimum python requirement in the documentation.
++ Removed redundant check in string checking code.
++ Add new options ``contains_regex`` and ``must_not_contain_regex`` to check
+  for regexes in files and stdout/stderr.
+
 version 1.3.0
 ---------------------------
 Python 3.6 and pytest 5.4.0.0 are now minimum requirements for pytest-workflow.

README.rst

@@ -28,6 +28,10 @@ pytest-workflow
   :target: https://codecov.io/gh/LUMC/pytest-workflow
   :alt:
 
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3757727.svg
+  :target: https://doi.org/10.5281/zenodo.3757727
+  :alt: More information on how to cite pytest-workflow here.
+
 pytest-workflow is a pytest plugin that aims to make pipeline/workflow testing easy
 by using yaml files for the test configuration.
 
@@ -37,8 +41,8 @@ For our complete documentation checkout our
 
 Installation
 ============
-Pytest-workflow requires Python 3.5 or higher. It is tested on Python 3.5, 3.6,
-3.7 and 3.8. Python 2 is not supported.
+Pytest-workflow requires Python 3.6 or higher. It is tested on Python 3.6, 3.7
+and 3.8. Python 2 is not supported.
 
 - Make sure your virtual environment is activated.
 - Install using pip ``pip install pytest-workflow``
@@ -124,5 +128,19 @@ predefined tests as well as custom tests are possible.
       must_not_contain:                # A list of strings which should NOT be in stderr (optional)
         - "Mission accomplished!"
 
+  - name: regex tests
+    command: echo Hello, world
+    stdout:
+      contains_regex:                  # A list of regex patterns that should be in stdout (optional)
+        - 'Hello.*'                    # Note the single quotes, these are required for complex regexes
+        - 'Hello .*'                   # This will fail, since there is a comma after Hello, not a space
+
+      must_not_contain_regex:          # A list of regex patterns that should not be in stdout (optional)
+        - '^He.*'                      # This will fail, since the regex matches Hello, world
+        - '^Hello .*'                  # Complex regexes will break yaml if double quotes are used
+
+For more information on how Python parses regular expressions, see the `Python
+documentation <https://docs.python.org/3.6/library/re.html>`_.
+
 Documentation for more advanced use cases including the custom tests can be
 found on our `readthedocs page <https://pytest-workflow.readthedocs.io/>`_.

docs/installation.rst

@@ -2,7 +2,7 @@
 Installation
 ============
 
-Pytest-workflow is tested on python 3.5, 3.6, 3.7 and 3.8. Python 2 is not
+Pytest-workflow is tested on python 3.6, 3.7 and 3.8. Python 2 is not
 supported.
 
 In a virtual environment

docs/known_issues.rst

@@ -10,4 +10,15 @@ Known issues
 
     coverage run --source=<your_source_here> -m py.test <your_test_dir>
 
-  This will work as expected.
+  This will work as expected.
+
++ ``contains_regex`` and ``must_not_contain_regex`` only work well with single
+  quotes in the yaml file. This is due to the way the yaml file is parsed: with
+  double quotes, special characters (like ``\t``) will be expanded, which can
+  lead to crashes.
+
++ Special care should be taken when using the backslash character (``\``) in
+  ``contains_regex`` and ``must_not_contain_regex``, since this collides with
+  Python's usage of the same character to escape special characters in strings.
+  Please see the `Python documentation on regular expressions
+  <https://docs.python.org/3.6/library/re.html>`_ for details.

docs/writing_tests.rst

@@ -68,9 +68,24 @@ Test options
       must_not_contain:                # A list of strings which should NOT be in stderr (optional)
         - "Mission accomplished!"
 
+  - name: regex tests
+    command: echo Hello, world
+    stdout:
+      contains_regex:                  # A list of regex patterns that should be in stdout (optional)
+        - 'Hello.*'                    # Note the single quotes, these are required for complex regexes
+        - 'Hello .*'                   # This will fail, since there is a comma after Hello, not a space
+
+      must_not_contain_regex:          # A list of regex patterns that should not be in stdout (optional)
+        - '^He.*'                      # This will fail, since the regex matches Hello, world
+        - '^Hello .*'                  # Complex regexes will break yaml if double quotes are used
+
 
 The above YAML file contains all the possible options for a workflow test.
 
+Please see the `Python documentation on regular expressions
+<https://docs.python.org/3.6/library/re.html>`_ to see how Python handles escape
+sequences.
+
 .. note::
     Workflow names must be unique. Pytest workflow will crash when multiple
     workflows have the same name, even if they are in different files.

setup.py

@@ -21,7 +21,7 @@
 
 setup(
     name="pytest-workflow",
-    version="1.3.0",
+    version="1.4.0",
     description="A pytest plugin for configuring workflow/pipeline tests "
                 "using YAML files",
     author="Leiden University Medical Center",

src/pytest_workflow/content_tests.py

@@ -21,6 +21,7 @@
 once."""
 import functools
 import gzip
+import re
 import threading
 from pathlib import Path
 from typing import Iterable, Optional, Set
@@ -55,14 +56,51 @@ def check_content(strings: Iterable[str],
             break
 
         for string in strings_to_check:
-            if string not in found_strings and string in line:
+            if string in line:
                 found_strings.add(string)
         # Remove found strings for faster searching. This should be done
         # outside of the loop above.
         strings_to_check -= found_strings
     return found_strings
 
 
+def check_regex_content(patterns: Iterable[str],
+                        text_lines: Iterable[str]) -> Set[str]:
+    """
+    Checks whether any of the patterns is present in the text lines
+    It only reads the lines once and it stops reading when
+    everything is found. This makes searching for patterns in large bodies of
+    text more efficient.
+    :param patterns: A list of regexes which is matched
+    :param text_lines: The lines of text that need to be searched.
+    :return: A tuple with a set of found regexes, and a set of not found
+    regexes
+    """
+
+    # Create two sets. By default all strings are not found.
+    regex_to_match = {re.compile(pattern) for pattern in patterns}
+    found_patterns: Set[str] = set()
+
+    for line in text_lines:
+        # Break the loop if all regexes have been matched
+        if not regex_to_match:
+            break
+
+        # Regexes we don't have to check anymore
+        to_remove = list()
+        for regex in regex_to_match:
+            if re.search(regex, line):
+                found_patterns.add(regex.pattern)
+                to_remove.append(regex)
+
+        # Remove found patterns for faster searching. This should be done
+        # outside of the loop above.
+        for regex in to_remove:
+            regex_to_match.remove(regex)
+
+    return found_patterns
+
+
 class ContentTestCollector(pytest.Collector):
     def __init__(self, name: str, parent: pytest.Collector,
                  filepath: Path,
@@ -84,6 +122,7 @@ def __init__(self, name: str, parent: pytest.Collector,
         self.content_test = content_test
         self.workflow = workflow
         self.found_strings = None
+        self.found_patterns = None
         self.thread = None
         # We check the contents of files. Sometimes files are not there. Then
         # content can not be checked. We save FileNotFoundErrors in this
@@ -99,6 +138,8 @@ def find_strings(self):
         self.workflow.wait()
         strings_to_check = (self.content_test.contains +
                             self.content_test.must_not_contain)
+        patterns_to_check = (self.content_test.contains_regex +
+                             self.content_test.must_not_contain_regex)
         file_open = (functools.partial(gzip.open, str(self.filepath))
                      if self.filepath.suffix == ".gz" else
                      self.filepath.open)
@@ -108,6 +149,11 @@ def find_strings(self):
                 self.found_strings = check_content(
                     strings=strings_to_check,
                     text_lines=file_handler)
+            # Read the file again for the regex
+            with file_open(mode='rt') as file_handler:  # type: ignore  # mypy goes crazy here otherwise  # noqa: E501
+                self.found_patterns = check_regex_content(
+                    patterns=patterns_to_check,
+                    text_lines=file_handler)
         except FileNotFoundError:
             self.file_not_found = True
 
@@ -124,6 +170,7 @@ def collect(self):
                 parent=self,
                 string=string,
                 should_contain=True,
+                regex=False,
                 content_name=self.content_name
             )
             for string in self.content_test.contains]
@@ -133,18 +180,39 @@ def collect(self):
                 parent=self,
                 string=string,
                 should_contain=False,
+                regex=False,
                 content_name=self.content_name
             )
             for string in self.content_test.must_not_contain]
 
+        test_items += [
+            ContentTestItem.from_parent(
+                parent=self,
+                string=pattern,
+                should_contain=True,
+                regex=True,
+                content_name=self.content_name
+            )
+            for pattern in self.content_test.contains_regex]
+
+        test_items += [
+            ContentTestItem.from_parent(
+                parent=self,
+                string=pattern,
+                should_contain=False,
+                regex=True,
+                content_name=self.content_name
+            )
+            for pattern in self.content_test.must_not_contain_regex]
+
         return test_items
 
 
 class ContentTestItem(pytest.Item):
     """Item that reports if a string has been found in content."""
 
     def __init__(self, parent: ContentTestCollector, string: str,
-                 should_contain: bool, content_name: str):
+                 should_contain: bool, regex: bool, content_name: str):
         """
         Create a ContentTestItem
         :param parent: A ContentTestCollector. We use a ContentTestCollector
@@ -153,6 +221,7 @@ def __init__(self, parent: ContentTestCollector, string: str,
         finished.
         :param string: The string that was searched for.
         :param should_contain: Whether the string should have been there
+        :param regex: Wether we are looking for a regex
         :param content_name: the name of the content which allows for easier
         debugging if the test fails
         """
@@ -163,6 +232,7 @@ def __init__(self, parent: ContentTestCollector, string: str,
         self.should_contain = should_contain
         self.string = string
         self.content_name = content_name
+        self.regex = regex
 
     def runtest(self):
         """Only after a workflow is finished the contents of files and logs are
@@ -175,8 +245,12 @@ def runtest(self):
         # Wait for thread to complete.
         self.parent.thread.join()
         assert not self.parent.file_not_found
-        assert ((self.string in self.parent.found_strings) ==
-                self.should_contain)
+        if self.regex:
+            assert ((self.string in self.parent.found_patterns) ==
+                    self.should_contain)
+        else:
+            assert ((self.string in self.parent.found_strings) ==
+                    self.should_contain)
 
     def repr_failure(self, excinfo, style=None):
         if self.parent.file_not_found:

src/pytest_workflow/file_tests.py

@@ -59,7 +59,9 @@ def collect(self):
             should_exist=self.filetest.should_exist,
             workflow=self.workflow)]
 
-        if self.filetest.contains or self.filetest.must_not_contain:
+        if any((self.filetest.contains, self.filetest.must_not_contain,
+                self.filetest.contains_regex,
+                self.filetest.must_not_contain_regex)):
             tests += [ContentTestCollector.from_parent(
                 name="content",
                 parent=self,

src/pytest_workflow/plugin.py

@@ -191,23 +191,12 @@ def pytest_collection():
 
 def get_workflow_names_from_workflow_marker(marker: MarkDecorator
                                             ) -> List[str]:
-    if not marker.name == "workflow":
-        raise ValueError(
-            f"Can only get names from markers named 'workflow' "
-            f"not '{marker.name}'.")
-    if marker.args:
-        return marker.args
-    elif 'name' in marker.kwargs:
-        # TODO: Remove this as soon as version reaches 1.4.0-dev
-        # This means also the entire get_workflow_names_from_workflow_marker
-        # function can be removed. As simply marker.args can be used.
-        warnings.warn(PendingDeprecationWarning(
+    if 'name' in marker.kwargs:
+        raise DeprecationWarning(
             "Using pytest.mark.workflow(name='workflow name') is "
-            "deprecated. Use pytest.mark.workflow('workflow_name') instead. "
-            "This behavior will be removed in a later version."))
-        return [marker.kwargs['name']]
-    else:
-        return []
+            "deprecated. Use pytest.mark.workflow('workflow_name') "
+            "instead.")
+    return marker.args
 
 
 def pytest_generate_tests(metafunc: Metafunc):

src/pytest_workflow/schema.py

@@ -106,22 +106,29 @@ def test_contains_concordance(dictionary: dict, name: str):
 
 class ContentTest(object):
     """
-    A class that holds two lists of strings. Everything in `contains` should be
-    present in the file/text
-    Everything in `must_not_contain` should not be present.
+    A class that holds four lists of strings. Everything in `contains` and
+    `contains_regex` should be present in the file/text
+    Everything in `must_not_contain` and `must_not_contain_regex` should
+    not be present.
     """
     def __init__(self, contains: Optional[List[str]] = None,
-                 must_not_contain: Optional[List[str]] = None):
+                 must_not_contain: Optional[List[str]] = None,
+                 contains_regex: Optional[List[str]] = None,
+                 must_not_contain_regex: Optional[List[str]] = None):
         self.contains: List[str] = contains or []
         self.must_not_contain: List[str] = must_not_contain or []
+        self.contains_regex: List[str] = contains_regex or []
+        self.must_not_contain_regex: List[str] = must_not_contain_regex or []
 
 
 class FileTest(ContentTest):
     """A class that contains all the properties of a to be tested file."""
     def __init__(self, path: str, md5sum: Optional[str] = None,
                  should_exist: bool = DEFAULT_FILE_SHOULD_EXIST,
                  contains: Optional[List[str]] = None,
-                 must_not_contain: Optional[List[str]] = None):
+                 must_not_contain: Optional[List[str]] = None,
+                 contains_regex: Optional[List[str]] = None,
+                 must_not_contain_regex: Optional[List[str]] = None):
         """
         A container object
         :param path: the path to the file
@@ -130,8 +137,14 @@ def __init__(self, path: str, md5sum: Optional[str] = None,
         :param contains: a list of strings that should be present in the file
         :param must_not_contain: a list of strings that should not be present
         in the file
+        :param contains_regex: a list of regular expression patterns that
+        should be present in the file
+        :param must_not_contain_regex: a list of regular expression pattersn
+        that should not be present in the file
         """
-        super().__init__(contains=contains, must_not_contain=must_not_contain)
+        super().__init__(contains=contains, must_not_contain=must_not_contain,
+                         contains_regex=contains_regex,
+                         must_not_contain_regex=must_not_contain_regex)
         self.path = Path(path)
         self.md5sum = md5sum
         self.should_exist = should_exist