Add PathComparer for testing and fix 2 test failure on Windows. (#5943)

commits are squashed.

* Add PathComparer for testing and fix 2 test failure on Windows.
* fix flake8
* add type information by f2f review. Thanks to @tk0miya!
* fix mypy, flake8 again..

sphinx/testing/comparer.py

@@ -0,0 +1,101 @@
+"""
+    sphinx.testing.comparer
+    ~~~~~~~~~~~~~~~~~~~~~~~
+
+    Sphinx test comparer for pytest
+
+    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+import difflib
+import pathlib
+from typing import List, Union
+
+
+class PathComparer:
+    """
+    OS-independent path comparison.
+
+    Windows path sep and posix path sep:
+
+    >>> '\\to\\index' == PathComparer('/to/index')
+    True
+    >>> '\\to\\index' == PathComparer('/to/index2')
+    False
+
+    Windows path with drive letters
+
+    >>> 'C:\\to\\index' == PathComparer('/to/index')
+    True
+    >>> 'C:\\to\\index' == PathComparer('C:/to/index')
+    True
+    >>> 'C:\\to\\index' == PathComparer('D:/to/index')
+    False
+    """
+    def __init__(self, path: Union[str, pathlib.Path]):
+        """
+        :param str path: path string, it will be cast as pathlib.Path.
+        """
+        self.path = pathlib.Path(path)
+
+    def __str__(self):
+        return self.path.as_posix()
+
+    def __repr__(self):
+        return "<{0.__class__.__name__}: '{0}'>".format(self)
+
+    def __eq__(self, other):
+        return not bool(self.ldiff(other))
+
+    def diff(self, other: Union[str, pathlib.Path]) -> List[str]:
+        """compare self and other.
+
+        When different is not exist, return empty list.
+
+        >>> PathComparer('/to/index').diff('C:\\to\\index')
+        []
+
+        When different is exist, return unified diff style list as:
+
+        >>> PathComparer('/to/index').diff('C:\\to\\index2')
+        [
+           '- C:/to/index'
+           '+ C:/to/index2'
+           '?            +'
+        ]
+        """
+        return self.ldiff(other)
+
+    def ldiff(self, other: Union[str, pathlib.Path]) -> List[str]:
+        return self._diff(
+            self.path,
+            pathlib.Path(other),
+        )
+
+    def rdiff(self, other: Union[str, pathlib.Path]) -> List[str]:
+        return self._diff(
+            pathlib.Path(other),
+            self.path,
+        )
+
+    def _diff(self, lhs: pathlib.Path, rhs: pathlib.Path) -> List[str]:
+        if lhs == rhs:
+            return []
+
+        if lhs.drive or rhs.drive:
+            # If either has a drive letter compare by absolute path
+            s_path, o_path = lhs.absolute().as_posix(), rhs.absolute().as_posix()
+        else:
+            s_path, o_path = lhs.as_posix(), rhs.as_posix()
+
+        if s_path == o_path:
+            return []
+
+        return [line.strip() for line in difflib.Differ().compare([s_path], [o_path])]
+
+
+def pytest_assertrepr_compare(op, left, right):
+    if isinstance(left, PathComparer) and op == "==":
+        return ['Comparing path:'] + left.ldiff(right)
+    if isinstance(right, PathComparer) and op == "==":
+        return ['Comparing path:'] + right.rdiff(left)

tests/conftest.py

@@ -14,6 +14,7 @@ import pytest
 
 import sphinx
 from sphinx.testing.path import path
+from sphinx.testing import comparer
 
 pytest_plugins = 'sphinx.testing.fixtures'
 
@@ -47,3 +48,7 @@ def _initialize_test_directory(session):
 
 def pytest_sessionstart(session):
     _initialize_test_directory(session)
+
+
+def pytest_assertrepr_compare(op, left, right):
+    comparer.pytest_assertrepr_compare(op, left, right)

tests/test_environment.py

@@ -11,6 +11,7 @@ import pytest
 
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.builders.latex import LaTeXBuilder
+from sphinx.testing.comparer import PathComparer
 
 
 @pytest.mark.sphinx('dummy')
@@ -84,7 +85,7 @@ def test_env_relfn2path(app):
 
     # relative filename and a document in subdir
     relfn, absfn = app.env.relfn2path('logo.jpg', 'subdir/index')
-    assert relfn == 'subdir/logo.jpg'
+    assert relfn == PathComparer('subdir/logo.jpg')
     assert absfn == app.srcdir / 'subdir' / 'logo.jpg'
 
     # absolute filename and a document in subdir
@@ -105,7 +106,7 @@ def test_env_relfn2path(app):
     # omit docname (w/ current docname)
     app.env.temp_data['docname'] = 'subdir/document'
     relfn, absfn = app.env.relfn2path('images/logo.jpg')
-    assert relfn == 'subdir/images/logo.jpg'
+    assert relfn == PathComparer('subdir/images/logo.jpg')
     assert absfn == app.srcdir / 'subdir' / 'images' / 'logo.jpg'
 
     # omit docname (w/o current docname)

tests/test_project.py

@@ -13,6 +13,7 @@ from collections import OrderedDict
 import pytest
 
 from sphinx.project import Project
+from sphinx.testing.comparer import PathComparer
 
 
 def test_project_discover(rootdir):
@@ -57,8 +58,8 @@ def test_project_path2doc(app):
     assert project.path2doc('index.foo') is None  # unknown extension
     assert project.path2doc('index.foo.rst') == 'index.foo'
     assert project.path2doc('index') is None
-    assert project.path2doc('/path/to/index.rst') == '/path/to/index'
-    assert project.path2doc(app.srcdir / '/to/index.rst') == '/to/index'
+    assert project.path2doc('/path/to/index.rst') == PathComparer('/path/to/index')
+    assert project.path2doc(app.srcdir / '/to/index.rst') == PathComparer('/to/index')
 
 
 @pytest.mark.sphinx(srcdir='project_doc2path', testroot='basic')