assertpy2 2.0.0__py3-none-any.whl

assertpy2/snapshot.py

@@ -0,0 +1,217 @@
+# Copyright (c) 2015-2019, Activision Publishing, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+# list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+from __future__ import annotations
+
+import datetime
+import inspect
+import json
+import os
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+__tracebackhide__ = True
+
+
+class SnapshotMixin:
+    """Snapshot mixin.
+
+    Take a snapshot of a python data structure, store it on disk in JSON format, and automatically
+    compare the latest data to the stored data on every test run.
+
+    Functional testing (which snapshot testing falls under) is very much blackbox testing.  When
+    something goes wrong, it's hard to pinpoint the issue, because functional tests typically
+    provide minimal *isolation* as compared to unit tests.  On the plus side, snapshots typically
+    do provide enormous *leverage* as a few well-placed snapshot tests can strongly verify that an
+    application is working.  Similar coverage would otherwise require dozens if not hundreds of
+    unit tests.
+
+    **On-disk Format**
+
+    Snapshots are stored in a readable JSON format.  For example::
+
+        assert_that({'a': 1, 'b': 2, 'c': 3}).snapshot()
+
+    Would be stored as::
+
+        {
+            "a": 1,
+            "b": 2,
+            "c": 3
+        }
+
+    The JSON formatting support most python data structures (dict, list, object, etc), but not custom
+    binary data.
+
+    **Updating**
+
+    It's easy to update your snapshots...just delete them all and re-run the test suite to regenerate all snapshots.
+
+    Note:
+        Snapshots require Python 3.x
+    """
+
+    def snapshot(self, id=None, path="__snapshots") -> Self:
+        """Asserts that val is identical to the on-disk snapshot stored previously.
+
+        On the first run of a test before the snapshot file has been saved, a snapshot is created,
+        stored to disk, and the test *always* passes.  But on all subsequent runs, val is compared
+        to the on-disk snapshot, and the test fails if they don't match.
+
+        Snapshot artifacts are stored in the ``__snapshots`` directory by default, and should be
+        committed to source control alongside any code changes.
+
+        Snapshots are identified by test filename plus line number by default.
+
+        Args:
+            id: the item or items expected to be contained
+            path: the item or items expected to be contained
+
+        Examples:
+            Usage::
+
+                assert_that(None).snapshot()
+                assert_that(True).snapshot()
+                assert_that(1).snapshot()
+                assert_that(123.4).snapshot()
+                assert_that('foo').snapshot()
+                assert_that([1, 2, 3]).snapshot()
+                assert_that({'a': 1, 'b': 2, 'c': 3}).snapshot()
+                assert_that({'a', 'b', 'c'}).snapshot()
+                assert_that(1 + 2j).snapshot()
+                assert_that(someobj).snapshot()
+
+            By default, snapshots are identified by test filename plus line number.  Alternately, you can specify a custom identifier using the ``id`` arg::
+
+                assert_that({'a': 1, 'b': 2, 'c': 3}).snapshot(id='foo-id')
+
+
+            By default, snapshots are stored in the ``__snapshots`` directory.  Alternately, you can specify a custom path using the ``path`` arg::
+
+                assert_that({'a': 1, 'b': 2, 'c': 3}).snapshot(path='my-custom-folder')
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** equal to on-disk snapshot
+        """
+
+        class _Encoder(json.JSONEncoder):
+            def default(self, o):
+                if isinstance(o, set):
+                    return {"__type__": "set", "__data__": list(o)}
+                elif isinstance(o, complex):
+                    return {"__type__": "complex", "__data__": [o.real, o.imag]}
+                elif isinstance(o, datetime.datetime):
+                    return {"__type__": "datetime", "__data__": o.strftime("%Y-%m-%d %H:%M:%S")}
+                elif "__dict__" in dir(o) and type(o) is not type:
+                    return {
+                        "__type__": "instance",
+                        "__class__": o.__class__.__name__,
+                        "__module__": o.__class__.__module__,
+                        "__data__": o.__dict__,
+                    }
+                return json.JSONEncoder.default(self, o)
+
+        class _Decoder(json.JSONDecoder):
+            def __init__(self):
+                json.JSONDecoder.__init__(self, object_hook=self.object_hook)
+
+            def object_hook(self, d):
+                if "__type__" in d and "__data__" in d:
+                    if d["__type__"] == "set":
+                        return set(d["__data__"])
+                    elif d["__type__"] == "complex":
+                        return complex(d["__data__"][0], d["__data__"][1])
+                    elif d["__type__"] == "datetime":
+                        return datetime.datetime.strptime(d["__data__"], "%Y-%m-%d %H:%M:%S")
+                    elif d["__type__"] == "instance":
+                        module_name = d["__module__"]
+                        if module_name not in sys.modules:
+                            return d
+                        mod = sys.modules[module_name]
+                        klass = getattr(mod, d["__class__"], None)
+                        if klass is None:
+                            return d
+                        inst = klass.__new__(klass)
+                        inst.__dict__ = d["__data__"]
+                        return inst
+                return d
+
+        def _save(name, val):
+            with open(name, "w") as fp:
+                json.dump(val, fp, indent=2, separators=(",", ": "), sort_keys=True, cls=_Encoder)
+
+        def _load(name):
+            with open(name) as fp:
+                return json.load(fp, cls=_Decoder)
+
+        def _name(path, name):
+            try:
+                return os.path.join(path, "snap-%s.json" % name.replace(" ", "_").lower())
+            except (TypeError, AttributeError):
+                raise ValueError("failed to create snapshot filename, either bad path or bad name") from None
+
+        if id:
+            # custom id
+            snapname = _name(path, id)
+        else:
+            # make id from filename and line number
+            f = inspect.currentframe()
+            fpath = os.path.basename(f.f_back.f_code.co_filename)
+            fname = os.path.splitext(fpath)[0]
+            lineno = str(f.f_back.f_lineno)
+            snapname = _name(path, fname)
+
+        if not os.path.exists(path):
+            os.makedirs(path)
+
+        if os.path.isfile(snapname):
+            # snap exists, so load
+            snap = _load(snapname)
+
+            if id:
+                # custom id, so test
+                return self.is_equal_to(snap)
+            else:
+                if lineno in snap:
+                    # found sub-snap, so test
+                    return self.is_equal_to(snap[lineno])
+                else:
+                    # lineno not in snap, so create sub-snap and pass
+                    snap[lineno] = self.val
+                    _save(snapname, snap)
+        else:
+            # no snap, so create and pass
+            _save(snapname, self.val if id else {lineno: self.val})
+
+        return self

assertpy2/string.py

@@ -0,0 +1,413 @@
+# Copyright (c) 2015-2019, Activision Publishing, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+# list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+from __future__ import annotations
+
+import collections.abc
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+__tracebackhide__ = True
+
+
+class StringMixin:
+    """String assertions mixin."""
+
+    def is_equal_to_ignoring_case(self, other) -> Self:
+        """Asserts that val is a string and is case-insensitive equal to other.
+
+        Checks actual is equal to expected using the ``==`` operator and ``str.lower()``.
+
+        Args:
+            other: the expected value
+
+        Examples:
+            Usage::
+
+                assert_that('foo').is_equal_to_ignoring_case('FOO')
+                assert_that('FOO').is_equal_to_ignoring_case('foo')
+                assert_that('fOo').is_equal_to_ignoring_case('FoO')
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if actual is **not** case-insensitive equal to expected
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if not isinstance(other, str):
+            raise TypeError("given arg must be a string")
+        if self.val.lower() != other.lower():
+            return self.error("Expected <%s> to be case-insensitive equal to <%s>, but was not." % (self.val, other))
+        return self
+
+    def contains_ignoring_case(self, *items) -> Self:
+        """Asserts that val is string and contains the given item or items.
+
+        Walks val and checks for item or items using the ``==`` operator and ``str.lower()``.
+
+        Args:
+            *items: the item or items expected to be contained
+
+        Examples:
+            Usage::
+
+                assert_that('foo').contains_ignoring_case('F', 'oO')
+                assert_that(['a', 'B']).contains_ignoring_case('A', 'b')
+                assert_that({'a': 1, 'B': 2}).contains_ignoring_case('A', 'b')
+                assert_that({'a', 'B'}).contains_ignoring_case('A', 'b')
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** contain the case-insensitive item or items
+        """
+        if len(items) == 0:
+            raise ValueError("one or more args must be given")
+        if isinstance(self.val, str):
+            if len(items) == 1:
+                if not isinstance(items[0], str):
+                    raise TypeError("given arg must be a string")
+                if items[0].lower() not in self.val.lower():
+                    return self.error(
+                        "Expected <%s> to case-insensitive contain item <%s>, but did not." % (self.val, items[0])
+                    )
+            else:
+                missing = []
+                for i in items:
+                    if not isinstance(i, str):
+                        raise TypeError("given args must all be strings")
+                    if i.lower() not in self.val.lower():
+                        missing.append(i)
+                if missing:
+                    return self.error(
+                        "Expected <%s> to case-insensitive contain items %s, but did not contain %s."
+                        % (self.val, self._fmt_items(items), self._fmt_items(missing))
+                    )
+        elif isinstance(self.val, collections.abc.Iterable):
+            missing = []
+            for i in items:
+                if not isinstance(i, str):
+                    raise TypeError("given args must all be strings")
+                found = False
+                for v in self.val:
+                    if not isinstance(v, str):
+                        raise TypeError("val items must all be strings")
+                    if i.lower() == v.lower():
+                        found = True
+                        break
+                if not found:
+                    missing.append(i)
+            if missing:
+                return self.error(
+                    "Expected <%s> to case-insensitive contain items %s, but did not contain %s."
+                    % (self.val, self._fmt_items(items), self._fmt_items(missing))
+                )
+        else:
+            raise TypeError("val is not a string or iterable")
+        return self
+
+    def starts_with(self, prefix) -> Self:
+        """Asserts that val is string or iterable and starts with prefix.
+
+        Args:
+            prefix: the prefix
+
+        Examples:
+            Usage::
+
+                assert_that('foo').starts_with('fo')
+                assert_that(['a', 'b', 'c']).starts_with('a')
+                assert_that((1, 2, 3)).starts_with(1)
+                assert_that(((1, 2), (3, 4), (5, 6))).starts_with((1, 2))
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** start with prefix
+        """
+        if prefix is None:
+            raise TypeError("given prefix arg must not be none")
+        if isinstance(self.val, str):
+            if not isinstance(prefix, str):
+                raise TypeError("given prefix arg must be a string")
+            if len(prefix) == 0:
+                raise ValueError("given prefix arg must not be empty")
+            if not self.val.startswith(prefix):
+                return self.error("Expected <%s> to start with <%s>, but did not." % (self.val, prefix))
+        elif isinstance(self.val, collections.abc.Iterable):
+            if len(self.val) == 0:
+                raise ValueError("val must not be empty")
+            first = next(iter(self.val))
+            if first != prefix:
+                return self.error("Expected %s to start with <%s>, but did not." % (self.val, prefix))
+        else:
+            raise TypeError("val is not a string or iterable")
+        return self
+
+    def ends_with(self, suffix) -> Self:
+        """Asserts that val is string or iterable and ends with suffix.
+
+        Args:
+            suffix: the suffix
+
+        Examples:
+            Usage::
+
+                assert_that('foo').ends_with('oo')
+                assert_that(['a', 'b', 'c']).ends_with('c')
+                assert_that((1, 2, 3)).ends_with(3)
+                assert_that(((1, 2), (3, 4), (5, 6))).ends_with((5, 6))
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** end with suffix
+        """
+        if suffix is None:
+            raise TypeError("given suffix arg must not be none")
+        if isinstance(self.val, str):
+            if not isinstance(suffix, str):
+                raise TypeError("given suffix arg must be a string")
+            if len(suffix) == 0:
+                raise ValueError("given suffix arg must not be empty")
+            if not self.val.endswith(suffix):
+                return self.error("Expected <%s> to end with <%s>, but did not." % (self.val, suffix))
+        elif isinstance(self.val, collections.abc.Iterable):
+            if len(self.val) == 0:
+                raise ValueError("val must not be empty")
+            items = list(self.val)
+            if items[-1] != suffix:
+                return self.error("Expected %s to end with <%s>, but did not." % (self.val, suffix))
+        else:
+            raise TypeError("val is not a string or iterable")
+        return self
+
+    def matches(self, pattern) -> Self:
+        """Asserts that val is string and matches the given regex pattern.
+
+        Args:
+            pattern (str): the regular expression pattern, as raw string (aka prefixed with ``r``)
+
+        Examples:
+            Usage::
+
+                assert_that('foo').matches(r'\\w')
+                assert_that('123-456-7890').matches(r'\\d{3}-\\d{3}-\\d{4}')
+
+            Match is partial unless anchored, so these assertion pass::
+
+                assert_that('foo').matches(r'\\w')
+                assert_that('foo').matches(r'oo')
+                assert_that('foo').matches(r'\\w{2}')
+
+            To match the entire string, just use an anchored regex pattern where ``^`` and ``$``
+            match the start and end of line and ``\\A`` and ``\\Z`` match the start and end of string::
+
+                assert_that('foo').matches(r'^\\w{3}$')
+                assert_that('foo').matches(r'\\A\\w{3}\\Z')
+
+            And regex flags, such as ``re.MULTILINE`` and ``re.DOTALL``, can only be applied via
+            *inline modifiers*, such as ``(?m)`` and ``(?s)``::
+
+                s = '''bar
+                foo
+                baz'''
+
+                # using multiline (?m)
+                assert_that(s).matches(r'(?m)^foo$')
+
+                # using dotall (?s)
+                assert_that(s).matches(r'(?s)b(.*)z')
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** match pattern
+
+        Tip:
+            Regular expressions are tricky.  Be sure to use raw strings (aka prefixed with ``r``).
+            Also, note that the :meth:`matches` assertion passes for partial matches (as does the
+            underlying ``re.match`` method).  So, if you need to match the entire string, you must
+            include anchors in the regex pattern.
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if not isinstance(pattern, str):
+            raise TypeError("given pattern arg must be a string")
+        if len(pattern) == 0:
+            raise ValueError("given pattern arg must not be empty")
+        if re.search(pattern, self.val) is None:
+            return self.error("Expected <%s> to match pattern <%s>, but did not." % (self.val, pattern))
+        return self
+
+    def does_not_match(self, pattern) -> Self:
+        """Asserts that val is string and does not match the given regex pattern.
+
+        Args:
+            pattern (str): the regular expression pattern, as raw string (aka prefixed with ``r``)
+
+        Examples:
+            Usage::
+
+                assert_that('foo').does_not_match(r'\\d+')
+                assert_that('123').does_not_match(r'\\w+')
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val **does** match pattern
+
+        See Also:
+            :meth:`matches` - for more about regex patterns
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if not isinstance(pattern, str):
+            raise TypeError("given pattern arg must be a string")
+        if len(pattern) == 0:
+            raise ValueError("given pattern arg must not be empty")
+        if re.search(pattern, self.val) is not None:
+            return self.error("Expected <%s> to not match pattern <%s>, but did." % (self.val, pattern))
+        return self
+
+    def is_alpha(self) -> Self:
+        """Asserts that val is non-empty string and all characters are alphabetic (using ``str.isalpha()``).
+
+        Examples:
+            Usage::
+
+                assert_that('foo').is_alpha()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** alphabetic
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if len(self.val) == 0:
+            raise ValueError("val is empty")
+        if not self.val.isalpha():
+            return self.error("Expected <%s> to contain only alphabetic chars, but did not." % self.val)
+        return self
+
+    def is_digit(self) -> Self:
+        """Asserts that val is non-empty string and all characters are digits (using ``str.isdigit()``).
+
+        Examples:
+            Usage::
+
+                assert_that('1234567890').is_digit()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** digits
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if len(self.val) == 0:
+            raise ValueError("val is empty")
+        if not self.val.isdigit():
+            return self.error("Expected <%s> to contain only digits, but did not." % self.val)
+        return self
+
+    def is_lower(self) -> Self:
+        """Asserts that val is non-empty string and all characters are lowercase (using ``str.lower()``).
+
+        Examples:
+            Usage::
+
+                assert_that('foo').is_lower()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** lowercase
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if len(self.val) == 0:
+            raise ValueError("val is empty")
+        if self.val != self.val.lower():
+            return self.error("Expected <%s> to contain only lowercase chars, but did not." % self.val)
+        return self
+
+    def is_upper(self) -> Self:
+        """Asserts that val is non-empty string and all characters are uppercase (using ``str.upper()``).
+
+        Examples:
+            Usage::
+
+                assert_that('FOO').is_upper()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** uppercase
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if len(self.val) == 0:
+            raise ValueError("val is empty")
+        if self.val != self.val.upper():
+            return self.error("Expected <%s> to contain only uppercase chars, but did not." % self.val)
+        return self
+
+    def is_unicode(self) -> Self:
+        """Asserts that val is a unicode string.
+
+        Examples:
+            Usage::
+
+                assert_that(u'foo').is_unicode()  # python 2
+                assert_that('foo').is_unicode()   # python 3
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** a unicode string
+        """
+        if not isinstance(self.val, str):
+            return self.error("Expected <%s> to be unicode, but was <%s>." % (self.val, type(self.val).__name__))
+        return self