Initial Test Suite (#58)

ntno · web-flow · commit b5af73251130 · 2023-01-11T14:07:56.000-05:00
* basic tests on tile macro
* empty id error fix
* fixed invalid img attributes
* fix missing alt attribute
* add img_width and img_height to docs
* test that img width and height are set by the image macro
* refactor make
* only run pytest on mac/linux
* future test for breaking change
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -8,19 +8,34 @@ jobs:
   test:
     strategy:
       matrix:
-        # python: ['3.7']
-        # platform: ['ubuntu-latest']
         python: ['3.7', '3.8', '3.9', '3.10']
         platform: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.platform }}
     steps:
-    - name: Checkout
-      uses: actions/checkout@v3
-    - name: Set up Python ${{ matrix.python }}
-      uses: actions/setup-python@v3
-      with:
-        python-version: ${{ matrix.python }}
-    - name: Install test dependencies
-      run: python -m pip install -U tox
-    - name: Test
-      run: python -m tox -e py
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python }}
+      - if: ${{ matrix.platform == 'ubuntu-latest' }} 
+        name: (ubuntu) Install Testing Prereqs
+        run: |
+          make USE_SUDO=1 install-test-prereqs
+      - if: ${{ matrix.platform == 'macos-latest' }} 
+        name: (macos) Install Testing Prereqs
+        run: |
+          brew install tidy-html5
+      - name: Install Tox
+        run: make install-tox
+      - name: Test Build/Package with Tox
+        run: python -m tox -e py
+      - if: ${{ matrix.platform == 'ubuntu-latest' }} 
+        name: (ubuntu) Run Tox pytests
+        run: |
+          python -m tox -e pytest-linux
+      - if: ${{ matrix.platform == 'macos-latest' }} 
+        name: (macos) Run Tox pytests
+        run: |
+          python -m tox -e pytest-darwin
+          
diff --git a/DEVELOPER_README.md b/DEVELOPER_README.md
@@ -127,7 +127,7 @@ make tox
 ```
 
 ### Add Tests
-Test suite setup is not complete yet.  See progress on this issue [here](https://github.com/ntno/mkdocs-terminal/issues/13).  If you have experience creating automated tests for Jinja2 please consider making a contribution!  
+Test suite setup is in progress.  See [GitHub issue](https://github.com/ntno/mkdocs-terminal/issues/13) for details.  If you have experience creating automated tests for Jinja2 please consider making a contribution!  
 
 ### Push Changes and Create PR
 See [Work On Pull Request](https://github.com/susam/gitpr#work-on-pull-request) for help on adding/pushing changes to your feature branch.  
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -13,4 +13,5 @@ exclude CONTRIBUTING.md
 exclude CODE_OF_CONDUCT.md
 exclude DEVELOPER_README.md
 exclude SECURITY.md
-exclude package-lock.json
+exclude package-lock.json
+exclude requirements.test.txt
diff --git a/Makefile b/Makefile
@@ -1,5 +1,8 @@
 version=$(shell cat package.json | jq .version -r)
 
+ifeq ($(USE_SUDO),1)
+   SUDO_FLAG = sudo
+endif
 
 .PHONY: check-version-match clean
 
@@ -52,15 +55,27 @@ clean-node:
 
 clean: clean-dist clean-node
 
-install-tox-requirements:
+install-test-prereqs:
+	$(SUDO_FLAG) apt-get update && $(SUDO_FLAG) apt install -y tidy
+
+install-test-requirements:	
+	pip install -r requirements.test.txt
+
+install-tox:
 	python -m pip install -U tox
 
-tox: install-tox-requirements
-	python -m tox -e py
+tox: install-tox install-test-prereqs
+	python -m tox -e py 
+	python -m tox -e pytest-linux
 
 check-version-match:
 	cat terminal/theme_version.html | grep -s --silent $(version)\"\>\$$ -o 
 
+#for developer use, assumes you have already installed prereqs
+quick-tests:
+	flake8 --ignore E501
+	pytest --color=yes --capture=no tests 
+
 check-site:
 ifndef site
 	$(error site is not set)
diff --git a/NOTES.md b/NOTES.md
@@ -35,3 +35,4 @@ Terminal for MkDocs' Tile Grid relies on the *meta*[^mkdocs-page-meta] attribute
   - img: https://picsum.photos/id/{id}/200/200  
 - to read: [Make for devops](https://alexharv074.github.io/2019/12/26/gnu-make-for-devops-engineers.html)  
 - to read: [testing bash scripts](https://alexharv074.github.io/2017/07/07/unit-testing-a-bash-script-with-shunit2.html)  
+- [pytidylib](https://pythonhosted.org/pytidylib/)
diff --git a/documentation/docs/tile-grid/tile.md b/documentation/docs/tile-grid/tile.md
@@ -33,6 +33,14 @@ A tile can represent an image, a link, or a linked image.
 
 :   Alternate text for the image if the image cannot be displayed.
 
+`img_width`
+
+:   Width to set on the image element.
+
+`img_height`
+
+:   Height to set on the image element.
+
 `link_href`
 
 :   Web page URL.  Can be an external web page or an internal MkDocs page like `./default/`.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "mkdocs-terminal",
-    "version": "1.2.3",
+    "version": "1.2.4",
     "description": "Terminal.css theme for MkDocs",
     "keywords": [
         "mkdocs",
@@ -25,4 +25,4 @@
     "engines": {
         "node": ">= 16"
     }
-}
+}
diff --git a/requirements.test.txt b/requirements.test.txt
@@ -0,0 +1,3 @@
+mkdocs
+pytest > 7
+pytidylib >= 0.3.2 
diff --git a/terminal/macros/tile-image.j2 b/terminal/macros/tile-image.j2
@@ -1,8 +1,8 @@
 {% macro make_image( tile ) -%}
 <img src="{{ tile.img_src }}" 
     {% if tile.img_title is defined and tile.img_title|length %}title="{{ tile.img_title }}"{% endif %} 
-    {% if tile.img_alt is defined and tile.img_alt|length %}alt="{{ tile.img_alt }}"{% endif %} 
-    width="{{ tile.img_width|default('auto', true ) }}"
-    height="{{ tile.img_height|default('auto', true ) }}"
+    alt="{{ tile.img_alt|default('', true ) }}"
+    {% if tile.img_width is defined and tile.img_width|length %}width="{{ tile.img_width }}"{% endif %} 
+    {% if tile.img_height is defined and tile.img_height|length %}height="{{ tile.img_height }}"{% endif %} 
 >
 {%- endmacro -%}
diff --git a/terminal/macros/tile.j2 b/terminal/macros/tile.j2
@@ -19,7 +19,11 @@
 
 
 {% if ns.is_valid %}
-<div id="{{ tile.id }}" class="terminal-mkdocs-tile {{ tile.class }}">
+<div 
+{% if tile.id is defined and tile.id|length %} 
+id="{{ tile.id }}" 
+{% endif %}
+class="terminal-mkdocs-tile {{ tile.class }}">
     <figure>
         {% if ns.has_link %} 
              {{ link_helper.make_link_start(tile) }}
diff --git a/terminal/theme_version.html b/terminal/theme_version.html
@@ -1 +1 @@
-<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-terminal-1.2.3">
+<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-terminal-1.2.4">
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -0,0 +1,90 @@
+from pathlib import Path
+from jinja2 import loaders
+from jinja2.environment import Environment
+import mkdocs.utils.filters
+import pytest
+from tests.utils.tile import Tile
+from tests import defaults
+
+
+@pytest.fixture
+def env():
+    """returns a new environment with mkdocs url filter."""
+    env = Environment()
+    env.filters['url'] = mkdocs.utils.filters.url_filter
+    return env
+
+
+@pytest.fixture
+def filesystem_terminal_loader():
+    """returns FileSystemLoader initialized to ../terminal directory"""
+    here = Path(__file__)
+    parent = here.parent
+    project_folder = parent.parent.resolve()
+    return loaders.FileSystemLoader(project_folder / "terminal")
+
+
+@pytest.fixture
+def env_with_terminal_loader(env, filesystem_terminal_loader):
+    """returns environment with loader set to terminal file system loader"""
+    env.loader = filesystem_terminal_loader
+    return env
+
+
+@pytest.fixture
+def empty_tile():
+    """returns an empty tile"""
+    return Tile()
+
+
+@pytest.fixture
+def minimal_link_tile():
+    """returns a minimal link only title"""
+    return Tile(link_href=defaults.GITHUB_LINK_HREF)
+
+
+@pytest.fixture
+def minimal_image_tile():
+    return Tile(img_src=defaults.GITHUB_IMG_SRC)
+
+
+@pytest.fixture
+def minimal_linked_image_tile():
+    return Tile(link_href=defaults.GITHUB_LINK_HREF, img_src=defaults.GITHUB_IMG_SRC)
+
+
+# @pytest.fixture
+# def dict_loader():
+#     """returns DictLoader"""
+#     return loaders.DictLoader({"justdict.html": "FOO"})
+
+
+# @pytest.fixture
+# def package_loader():
+#     """returns PackageLoader initialized from templates"""
+#     return loaders.PackageLoader("res", "templates")
+
+
+# @pytest.fixture
+# def filesystem_loader():
+#     """returns FileSystemLoader initialized to res/templates directory"""
+#     here = Path(__file__).parent.resolve()
+#     return loaders.FileSystemLoader(here / "res" / "templates")
+
+
+# @pytest.fixture
+# def function_loader():
+#     """returns a FunctionLoader"""
+#     return loaders.FunctionLoader({"justfunction.html": "FOO"}.get)
+
+
+# @pytest.fixture
+# def choice_loader(dict_loader, package_loader):
+#     """returns a ChoiceLoader"""
+#     return loaders.ChoiceLoader([dict_loader, package_loader])
+
+
+# @pytest.fixture
+# def prefix_loader(filesystem_loader, dict_loader):
+#     """returns a PrefixLoader"""
+#     return loaders.PrefixLoader({"a": filesystem_loader, "b": dict_loader})
diff --git a/tests/defaults.py b/tests/defaults.py
@@ -0,0 +1,6 @@
+GITHUB_LINK_HREF = "https://github.com"
+GITHUB_IMG_SRC = "https://github.githubassets.com/favicons/favicon.svg"
+GITHUB_IMG_ALT = "the GitHub Octopuss logo"
+GITHUB_IMG_TITLE = "GitHub's Octopuss logo"
+GITHUB_IMG_WIDTH = "100"
+GITHUB_IMG_HEIGHT = "200"
diff --git a/tests/test_simple.py b/tests/test_simple.py
diff --git a/tests/test_test_setup.py b/tests/test_test_setup.py
@@ -0,0 +1,11 @@
+from jinja2 import TemplateNotFound
+
+
+class TestTestSetup():
+
+    def test_filesystem_terminal_loader_can_load_terminal_template(self, env_with_terminal_loader):
+        try:
+            found_template = env_with_terminal_loader.get_template("base.html")
+            assert found_template is not None
+        except TemplateNotFound:
+            self.fail("base.html should be found")
diff --git a/tests/test_tile.py b/tests/test_tile.py
@@ -0,0 +1,62 @@
+from tests.utils.tile import Tile
+from tests.utils.html import check_html
+from tests import defaults
+import pytest
+
+
+class TestTile():
+
+    def test_empty_tile(self, env_with_terminal_loader, empty_tile):
+        assert isinstance(empty_tile, Tile)
+
+        tile_macro = env_with_terminal_loader.get_template("macros/tile.j2")
+        rendered_tile = tile_macro.module.make_tile(empty_tile)
+        assert rendered_tile.strip() == ""
+        assert len(check_html(rendered_tile)["errors"]) == 0
+
+    def test_minimal_link_tile(self, env_with_terminal_loader, minimal_link_tile):
+        assert isinstance(minimal_link_tile, Tile)
+
+        tile_macro = env_with_terminal_loader.get_template("macros/tile.j2")
+        rendered_tile = tile_macro.module.make_tile(minimal_link_tile)
+        assert rendered_tile.strip() != ""
+        assert "<a " in rendered_tile
+        assert "</a>" in rendered_tile
+        assert "<img " not in rendered_tile
+        assert "id=" not in rendered_tile
+        # TODO assert contains <div/figure/a
+        assert len(check_html(rendered_tile)["errors"]) == 0
+
+    def test_minimal_image_tile(self, env_with_terminal_loader, minimal_image_tile):
+        assert isinstance(minimal_image_tile, Tile)
+        tile_macro = env_with_terminal_loader.get_template("macros/tile.j2")
+        rendered_tile = tile_macro.module.make_tile(minimal_image_tile)
+        assert rendered_tile.strip() != ""
+        assert "<a " not in rendered_tile
+        assert "</a>" not in rendered_tile
+        assert "<img " in rendered_tile
+        assert "id=" not in rendered_tile
+        # TODO assert contains <div/figure/img>
+        assert len(check_html(rendered_tile)["errors"]) == 0
+
+    def test_minimal_linked_img_tile(self, env_with_terminal_loader, minimal_linked_image_tile):
+        assert isinstance(minimal_linked_image_tile, Tile)
+        tile_macro = env_with_terminal_loader.get_template("macros/tile.j2")
+        rendered_tile = tile_macro.module.make_tile(minimal_linked_image_tile)
+        assert rendered_tile.strip() != ""
+        assert "<a " in rendered_tile
+        assert "</a>" in rendered_tile
+        assert "<img " in rendered_tile
+        assert "id=" not in rendered_tile
+        # TODO assert contains <div/figure/a/img>
+        assert len(check_html(rendered_tile)["errors"]) == 0
+
+    @pytest.mark.skip(reason="breaking change needs to be fixed in major release")
+    def test_id_and_class_added_to_tile(self, env_with_terminal_loader):
+        tile = Tile(html_id="myId", css_class="myClass", link_href=defaults.GITHUB_LINK_HREF)
+        tile_macro = env_with_terminal_loader.get_template("macros/tile.j2")
+        rendered_tile = tile_macro.module.make_tile(tile)
+        assert rendered_tile.strip() != ""
+        assert "id=\"myID\"" in rendered_tile
+        assert "class=\"terminal-mkdocs-tile myClass\"" in rendered_tile
+        assert len(check_html(rendered_tile)["errors"]) == 0
diff --git a/tests/test_tile_image.py b/tests/test_tile_image.py
diff --git a/tests/test_tile_link.py b/tests/test_tile_link.py
diff --git a/tests/utils/html.py b/tests/utils/html.py
diff --git a/tests/utils/tile.py b/tests/utils/tile.py
diff --git a/tox.ini b/tox.ini

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "mkdocs-terminal",`
`3`		`- "version": "1.2.3",`
	`3`	`+ "version": "1.2.4",`
`4`	`4`	`"description": "Terminal.css theme for MkDocs",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"mkdocs",`
`@@ -25,4 +25,4 @@`
`25`	`25`	`"engines": {`
`26`	`26`	`"node": ">= 16"`
`27`	`27`	`}`
`28`		`-}`
	`28`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+mkdocs`
	`2`	`+pytest > 7`
	`3`	`+pytidylib >= 0.3.2`