Add unit testing (hellt#5)

mjbear · web-flow · commit 74441dbe2437 · 2024-09-23T08:28:59.000+02:00
added unit testing
diff --git a/.github/workflows/cicd.yml b/.github/workflows/cicd.yml
@@ -1,4 +1,4 @@
-name: Build and Push Docker Image
+name: Test, Build and Push Docker Image
 
 "on":
   push:
@@ -8,10 +8,31 @@ name: Build and Push Docker Image
   pull_request:
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    env:
+      test_dir: tests
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run Python unit tests
+        run: python -m unittest discover -s ${{ env.test_dir }}
+
   docker:
     runs-on: ubuntu-latest
     permissions:
       packages: write
+    needs:
+      - "test"
     steps:
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
@@ -36,12 +57,12 @@ jobs:
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
-          username: ${{ github.repository_owner }}
+          username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push
         uses: docker/build-push-action@v6
         with:
           push: true
           platforms: linux/amd64,linux/arm64
-          tags: ${{ steps.meta.outputs.tags }}
+          tags: ${{ steps.meta.outputs.tags }}
diff --git a/.gitignore b/.gitignore
@@ -160,3 +160,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# vim
+*.swp
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,58 @@
+# Contributing
+
+🎉 Thank you for your interest in contributing to this project! 🎉
+
+A couple of quick items:
+
+1. To avoid duplicate issues and PRs, [please search open issue and pull requests](https://docs.github.com/en/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) before submitting a new one.
+1. The general expectation is to [submit a GitHub issue](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue) to receive feedback before submitting a pull request (PR) with changes.
+    * _This will help ensure ideas align with the project scope._
+1. Unit tests should accompany [Pull Requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) **whenever possible**. :point_left:
+    * This could mean adding additional tests to an existing unit test file or creating a new one.
+
+## Ways to Contribute
+
+(in no particular order)
+
+* Code
+* Documentation
+* Expanding Unit Test coverage (where needed)
+* Helping others (ex: with [issue tickets](https://github.com/hellt/markdown-footnote-sorter/issues))
+
+## Testing Framework
+
+For minimal dependencies, the "batteries included" [Python `unittest` framework](https://docs.python.org/3/library/unittest.html) is utilized. (Other testing frameworks could be considered should additional testing features be needed.)
+
+## Development Process
+>
+> This section consists of suggestions.
+
+It is recommended to verify tests are successful before making any code changes. From there make your changes and run the unit tests to validate there is not code regression.
+
+* [Create a fork of this project](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
+  * If you have an existing fork of this project be sure [to synchronize it](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)!
+* From the `main` branch of your fork, [create a feature branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)
+* Validate [test cases run successfully](#running-unit-tests) before any changes are made
+* Make modifications
+* Re-test with the existing unit tests against the modified codebase
+* Add any additional unit tests to improve testing coverage
+* Re-run the unit tests to confirm they run successfully
+* When you are satisfied with the changes and it is ready for review, [submit a Pull Request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
+
+## Running Unit Tests
+
+Choose one of the below testing commands methods that suits your needs.
+
+> [!IMPORTANT]
+> The commands below are to be run from the top level of the project.
+
+1. Discover and run unit tests
+    * `python -m unittest discover`
+
+1. Verbose version of unit test discovery
+    * `python -m unittest discover -v`
+
+1. Discover unit tests in specific directory (in this case, `tests`) with verbosity
+    * `python -m unittest discover -s tests -v`
+
+💡 For additional `unittest` command line options, refer to the [official Python unittest documentation](https://docs.python.org/3/library/unittest.html#command-line-interface).
diff --git a/README.md b/README.md
@@ -28,3 +28,7 @@ Or download the script and put it in your `$PATH`:
 ```bash
 curl -sL https://raw.githubusercontent.com/hellt/markdown-footnote-sorter/main/fnsort.py
 ```
+
+
+## Contributing
+For information about contributing to this project, see the [contributing guidelines](CONTRIBUTING.md).
diff --git a/tests/__init__.py b/tests/__init__.py
diff --git a/tests/default/example.md b/tests/default/example.md
@@ -0,0 +1,18 @@
+# Footnote sorter demo
+
+The text below has multiple footnotes that are all messed up. Footnote sorter will sort them for you.
+
+You like hedgehogs[^1], right? Well, echidnas[^3] are like hedgehogs, but bigger and better. They're
+also knkown as spiny anteaters[^4], and they're one of the only mammals
+that lay eggs (the other
+being a platypus). Pretty neat eh[^2]?
+
+[^2]: super cool
+[^1]: hedgehogs are cool, but echidnas are cooler.
+and soon you'll see our mascot
+[^3]: actually
+    you can put complex stuff in the footnotes, like tabs
+    /// tab | yo
+    content
+    ///
+[^4]: What a name!
diff --git a/tests/default/example_expected.md b/tests/default/example_expected.md
@@ -0,0 +1,18 @@
+# Footnote sorter demo
+
+The text below has multiple footnotes that are all messed up. Footnote sorter will sort them for you.
+
+You like hedgehogs[^1], right? Well, echidnas[^2] are like hedgehogs, but bigger and better. They're
+also knkown as spiny anteaters[^3], and they're one of the only mammals
+that lay eggs (the other
+being a platypus). Pretty neat eh[^4]?
+
+[^1]: hedgehogs are cool, but echidnas are cooler.
+and soon you'll see our mascot
+[^2]: actually
+    you can put complex stuff in the footnotes, like tabs
+    /// tab | yo
+    content
+    ///
+[^3]: What a name!
+[^4]: super cool
diff --git a/tests/duplicates/duplicates.md b/tests/duplicates/duplicates.md
@@ -0,0 +1,15 @@
+# Example markdown with duplicate footnotes
+
+Horned lizards[^1] are pretty cool too. They're spiny like echidnas[^3], but they're messy since horned lizards [^1] squirt blood from their eyes when threatened.
+
+They are also called horntoads[^2], but are classified as reptiles.
+
+The horns on its head are true horns[^5] as they have a bony core, but the spines on the back are not as they are modified reptile scales to prevent water loss[^4].
+
+Fifteen of the twenty-one species are native to the United States. The Texas horned lizard is not only the largest-bodied horned lizard, but also most widely distributed of the American horned lizard species [^3].
+
+[^1]: the more spiky, the better
+[^3]: really cool
+[^2]: a bit of a misnomer, right?
+[^5]: not to be confused with antlers, since horns don't fall off each year
+[^4]: it's hot in the desert
diff --git a/tests/duplicates/duplicates_expected.md b/tests/duplicates/duplicates_expected.md
@@ -0,0 +1,15 @@
+# Example markdown with duplicate footnotes
+
+Horned lizards[^1] are pretty cool too. They're spiny like echidnas[^2], but they're messy since horned lizards [^1] squirt blood from their eyes when threatened.
+
+They are also called horntoads[^3], but are classified as reptiles.
+
+The horns on its head are true horns[^4] as they have a bony core, but the spines on the back are not as they are modified reptile scales to prevent water loss[^5].
+
+Fifteen of the twenty-one species are native to the United States. The Texas horned lizard is not only the largest-bodied horned lizard, but also most widely distributed of the American horned lizard species [^2].
+
+[^1]: the more spiky, the better
+[^2]: really cool
+[^3]: a bit of a misnomer, right?
+[^4]: not to be confused with antlers, since horns don't fall off each year
+[^5]: it's hot in the desert
diff --git a/tests/fn_must_be_last/must_be_last.md b/tests/fn_must_be_last/must_be_last.md
@@ -0,0 +1,16 @@
+# Footnotes must be last
+Footnotes must be last otherwise the other content will be lost.
+
+Red deer[^red_deer] are interesting as well.
+The range is vast with red deer native to western Europe, western Asia, parts of the Middle East, and even northern Africa[^n_africa]!
+There is a herd of roughly 3000 red deer living in The Netherlands' Oostvaardersplassen [^nl_reserve] (a nature reserve).
+The male red deer are referred to as stag or hart [^red_deer] whereas the females are doe or hind and the young are calves.
+
+The size [^desc] of the red deer stags can rival that of North America elk if an ample food supply is present. Red deer are the fourth largest[^size] extant deer species behind moose, elk, and sambar deer.
+
+[^nl_reserve]: https://en.wikipedia.org/wiki/Oostvaardersplassen
+[^n_africa]: https://en.wikipedia.org/wiki/Northern_Africa
+[^desc]: https://en.wikipedia.org/wiki/Red_deer#Description
+[^size]: https://en.wikipedia.org/wiki/Red_deer#Size
+[^red_deer]: https://en.wikipedia.org/wiki/Red_deer
+<!--- I tried to stash a comment at the bottom, but it will be shuffled around --->
diff --git a/tests/fn_must_be_last/must_be_last_expected.md b/tests/fn_must_be_last/must_be_last_expected.md
@@ -0,0 +1,16 @@
+# Footnotes must be last
+Footnotes must be last otherwise the other content will be lost.
+
+Red deer[^1] are interesting as well.
+The range is vast with red deer native to western Europe, western Asia, parts of the Middle East, and even northern Africa[^2]!
+There is a herd of roughly 3000 red deer living in The Netherlands' Oostvaardersplassen [^3] (a nature reserve).
+The male red deer are referred to as stag or hart [^1] whereas the females are doe or hind and the young are calves.
+
+The size [^4] of the red deer stags can rival that of North America elk if an ample food supply is present. Red deer are the fourth largest[^5] extant deer species behind moose, elk, and sambar deer.
+
+[^1]: https://en.wikipedia.org/wiki/Red_deer
+[^2]: https://en.wikipedia.org/wiki/Northern_Africa
+[^3]: https://en.wikipedia.org/wiki/Oostvaardersplassen
+[^4]: https://en.wikipedia.org/wiki/Red_deer#Description
+[^5]: https://en.wikipedia.org/wiki/Red_deer#Size
+<!--- I tried to stash a comment at the bottom, but it will be shuffled around --->
diff --git a/tests/test_footnote_sorting.py b/tests/test_footnote_sorting.py
@@ -0,0 +1,115 @@
+import unittest
+
+import fnsort
+
+class TestDefaults(unittest.TestCase):
+    @classmethod
+    def setUpClass(self):
+        # example markdown files intentionally have had trailing EOL trimmed
+        #   from the end of the file (EOF)
+
+        path = "tests/default"
+
+        with open(f"{path}/example.md") as fh:
+            self.text = fh.read()
+
+        with open(f"{path}/example_expected.md") as fh:
+            self.expected_text = fh.read()
+
+        # allow for full diff output
+        # self.maxDiff = None
+
+
+    def test_replace_reference(self):
+        """ Inline reference replacement """
+        # use the link regex from the fnsort import
+           
+        # "search" function only returns the first match
+        match = fnsort.link.search(self.text)
+        order = ["1", "3", "4", "2"]
+
+        # hedgehogs[^1]
+        self.assertEqual(
+            fnsort.refrepl(match, order),
+            "s[^1]"
+        )
+
+
+    def test_footnote_sort(self):
+        """ Entire footnote sort process """
+        self.assertEqual(fnsort.sort_footnotes(self.text), self.expected_text)
+
+
+class TestDuplicates(unittest.TestCase):
+    @classmethod
+    def setUpClass(self):
+        path = "tests/duplicates"
+
+        with open(f"{path}/duplicates.md") as fh:
+            self.text = fh.read()
+
+        with open(f"{path}/duplicates_expected.md") as fh:
+            self.expected_text = fh.read()
+
+        # allow for full diff output
+        # self.maxDiff = None
+
+
+    def test_replace_references_with_dups(self):
+        """ Multiple reference replacements with duplicate tags """
+        # find all matches
+        matches = fnsort.link.finditer(self.text)
+        order = ["1", "3", "2", "5", "4"]
+
+        # should be seven regex matches in duplicates.md
+        expected = [
+            "s[^1]", "s[^2]", " [^1]", "s[^3]", "s[^4]", "s[^5]", " [^2]"
+        ]
+
+        # multiple assertions
+        for i, match in enumerate(matches):
+            self.assertEqual(
+                fnsort.refrepl(match, order),
+                expected[i]
+            )
+
+
+    def test_footnote_sort_with_dups(self):
+        """ Entire footnote sort process with duplicate tags """
+        self.assertEqual(fnsort.sort_footnotes(self.text), self.expected_text)
+
+
+class TestFootnotesMustBeLast(unittest.TestCase):
+    @classmethod
+    def setUpClass(self):
+        path = "tests/fn_must_be_last"
+
+        with open(f"{path}/must_be_last.md") as fh:
+            self.text = fh.read()
+
+        with open(f"{path}/must_be_last_expected.md") as fh:
+            self.expected_text = fh.read()
+
+        # allow for full diff output
+        # self.maxDiff = None
+
+
+    def test_footnote_sort_trailing_text(self):
+        """ [negative test] Entire footnote sort process with text after the footnotes """
+
+        """
+        negative test
+
+        text after the last footnote will be captured as part of that
+          footnote creating a choppy looking list
+
+        in short this is not expected to return the desired output
+
+        just so happened to luck out that the last footnote reference of the
+            "duplicates" example was indeed the last footnote :shrug:
+        """
+        self.assertNotEqual(fnsort.sort_footnotes(self.text), self.expected_text)
+
+
+if __name__ == "__main__":
+    unittest.main()
