chore: Configure Poe the Poet (#19)

Author: TheLandolorien

.github/hooks/pre-commit

@@ -1,24 +1,15 @@
 #!/bin/sh
 
-black_formatting_results=$(poetry run black --check --line-length 100 . 2>&1 > /dev/null)
+formatting_results=$(poe format 2>&1 > /dev/null)
 if [[ "$?" == "0" ]]; then
-    echo "✅ Source Code Formatting"
+    echo "✅ Formatting"
 else
-    echo "❌ Source Code Formatting"
-    echo "$black_formatting_results"
+    echo "❌ Formatting"
+    echo "$formatting_results"
 	exit 1
 fi
 
-prettier_formatting_results=$(npx --yes prettier@3.0.3 . --no-config --check --log-level warn 2>&1 >/dev/null)
-if [[ "$?" == "0" ]]; then
-    echo "✅ Supplemental Code Formatting"
-else
-    echo "❌ Supplemental Code Formatting"
-    echo "$prettier_formatting_results"
-	exit 1
-fi
-
-linting_results=$(poetry run pylint src tests)
+linting_results=$(poe lint 2>&1 > /dev/null)
 if [[ "$?" == "0" ]]; then
     echo "✅ Linting"
 else
@@ -27,11 +18,11 @@ else
 	exit 1
 fi
 
-test_results=$(poetry run pytest tests/unit tests/integration --cov=src/package_name --cov-fail-under=90 --no-header --no-summary -qq --cov=src/package_name --cov-report term-missing:skip-covered --cov-branch --cov-fail-under=90)
+test_results=$(poe test)
 if [[ "$?" == "0" ]]; then
-	echo "✅ Unit/Integration Tests"
+	echo "✅ Test Coverage"
 else
-	echo "❌ Unit/Integration Tests"
+	echo "❌ Test Coverage"
 	echo "$test_results"
 	exit 1
 fi

.github/hooks/pre-push

@@ -1,6 +1,6 @@
 #!/bin/sh
 
-test_results=$(poetry run pytest --no-header -qq tests/e2e)
+test_results=$(poe test-e2e)
 if [[ "$?" == "0" ]]; then
 	echo "✅ End-to-End Tests"
 else

README.md

@@ -12,7 +12,7 @@
 
 ## 🎧 Quick Start
 
-Ensure [Python](https://www.python.org/downloads) and [Python Poetry](https://python-poetry.org/docs/#installation) are installed.
+Ensure [Python](https://www.python.org/downloads), [Python Poetry](https://python-poetry.org/docs/#installation), and [Poe the Poet](https://poethepoet.natn.io/installation.html) are installed.
 
 Dependency installation is managed via `poetry`. Once cloned, you can install dependencies from the project root:
 
@@ -28,26 +28,6 @@ poetry run package-name
 
 And boom! You're ready to customize a Python project! 🎉
 
-## 🧪 Running Tests
-
-[`pytest`](https://docs.pytest.org/en/7.4.x/) is used as a test runner and its configuration can be found in the `tool.pytest.ini_options` section of [pyproject.toml](./pyproject.toml). [`pytest-cov`](https://pytest-cov.readthedocs.io/en/latest/index.html) is used as a coverage reporter.
-
-Running `pytest` with no arguments will:
-
-- Automatically add `src` to `PYTHONPATH` (pythonpath: `src`)
-- Only run unit tests (testpaths: `tests/unit/package_name`)
-- Increase verbosity (`-vv`)
-- Calculate coverage (using `pytest-cov`) and display any modules missing coverage
-
-You can specify different paths to run different groupings of tests:
-
-```shell
-pytest tests/unit         # Run unit tests
-pytest tests/integration  # Run integration tests
-pytest tests/e2e          # Run end-to-end tests
-pytest tests              # Run all tests
-```
-
 ## Configuring Developer Standards
 
 Use `git` to install commit message, pre-commit, and pre-push commit hooks:
@@ -61,6 +41,50 @@ These will ensure commit messages are consistent, code is correctly formatted an
 
 Style decisions are based on the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html).
 
+## 🧑🏽‍💻 Running Project Tasks
+
+[`poe`](https://poethepoet.natn.io/index.html) is used as a task runner and its configuration can be found in the `tool.poe.tasks*` sections of [pyproject.toml](./pyproject.toml).
+
+| Command                | Summary                                               | Bash Equivalent                                                                                                                                                                                                   |
+| ---------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `poe test`             | Run application test suites that support coverage     | `PYTHONPATH=src poetry run pytest -vv --import-mode=importlib --cov=src/package_name --cov-fail-under=90 --cov=src/package_name --cov-branch --cov-report term-missing:skip-covered tests/unit tests/integration` |
+| `poe test-all`         | Run all tests (without coverage)                      | `PYTHONPATH=src pytest -vv --import-mode=importlib`                                                                                                                                                               |
+| `poe test-e2e`         | Run e2e tests only                                    | `PYTHONPATH=src poetry run pytest -vv --import-mode=importlib tests/e2e`                                                                                                                                          |
+| `poe test-integration` | Run integration tests only (with coverage)            | `PYTHONPATH=src poetry run pytest -vv --import-mode=importlib --cov=src/package_name --cov-fail-under=90 --cov=src/package_name --cov-branch --cov-report term-missing:skip-covered tests/integration`            |
+| `poe test-unit`        | Run unit tests only (without coverage)                | `PYTHONPATH=src poetry run pytest -vv --import-mode=importlib tests/unit`                                                                                                                                         |
+| `poe check`            | Run all formatting and linting tools against codebase | `poetry run black --check --line-length 100 . && npx --yes prettier@3.0.3 . --no-config --check && poetry run pylint src tests`                                                                                   |
+| `poe format`           | Run all formatting tools against codebase             | `poetry run black --check --line-length 100 . && npx --yes prettier@3.0.3 . --no-config --check`                                                                                                                  |
+| `poe format-black`     | Run black against Python source code                  | `poetry run black --check --line-length 100 .`                                                                                                                                                                    |
+| `poe format-prettier`  | Run prettier against non-Python code                  | `npx --yes prettier@3.0.3 . --no-config --check`                                                                                                                                                                  |
+| `poe lint`             | Run all linting tools against codebase                | `poetry run pylint src tests`                                                                                                                                                                                     |
+| `poe lint-pylint`      | Lint Python source code and tests with pylint         | `poetry run pylint src tests`                                                                                                                                                                                     |
+
+## 🧪 Testing Configuration
+
+[`pytest`](https://docs.pytest.org/en/7.4.x/) is used as a test runner and its configuration can be found in the `tool.pytest.ini_options` section of [pyproject.toml](./pyproject.toml). [`pytest-cov`](https://pytest-cov.readthedocs.io/en/latest/index.html) is used as a coverage reporter.
+
+Running `pytest` with no arguments will:
+
+- Automatically add `src` to the `PYTHONPATH` (pythonpath: `src`)
+- Increase verbosity (`-vv`)
+- Override pytest's historical default import mode to `importlib` which is recommended for new projects (`--import-mode=importlib`)
+- Run all available test items in [`./tests/`](./tests)
+
+Tests are grouped into suites using different path names:
+
+```shell
+tests/
+├── conftest.py
+├── ci/
+│   └── ...
+├── e2e/
+│   └── ...
+├── integration/
+│   └── ...
+└── unit/
+    └── ...
+```
+
 ## 🪪 License
 
 This tool is [MIT licensed](./LICENSE).

pyproject.toml

@@ -45,12 +45,59 @@ disable = ["missing-module-docstring"]
 [tool.pytest.ini_options]
 minversion = "7.4.0"
 pythonpath = "src"
-testpaths = ["tests/unit", "tests/integration"]
 addopts = "-vv --import-mode=importlib"
 
 [tool.poetry.scripts]
 package-name = "package_name.cli:run"
 
+[tool.poe.tasks.test]
+help = "Default: Run application test suites that support coverage"
+sequence = ["test-coverage"]
+
+[tool.poe.tasks.test-all]
+help = "Run all application test suites"
+sequence = ["test-unit", "test-integration", "test-e2e"]
+
+[tool.poe.tasks.test-coverage]
+help = "Run application test suites that support coverage"
+cmd = "pytest --cov=src/package_name --cov-fail-under=90 --cov=src/package_name --cov-branch --cov-report term-missing:skip-covered tests/unit tests/integration"
+
+[tool.poe.tasks.test-e2e]
+help = "Run e2e tests only"
+cmd = "pytest tests/e2e"
+
+[tool.poe.tasks.test-integration]
+help = "Run integration tests only (with coverage)"
+cmd = "pytest --cov=src/package_name --cov-fail-under=90 --cov=src/package_name --cov-branch --cov-report term-missing:skip-covered tests/integration"
+
+[tool.poe.tasks.test-unit]
+help = "Run unit tests only (without coverage)"
+cmd = "pytest tests/unit"
+
+[tool.poe.tasks.check]
+help = "Check code quality"
+sequence = ["format", "lint"]
+
+[tool.poe.tasks.lint]
+help = "Run all linting tools against codebase"
+sequence = ["lint-pylint"]
+
+[tool.poe.tasks.lint-pylint]
+help = "Lint Python source code and tests with pylint"
+cmd = "pylint --verbose --score y src tests"
+
+[tool.poe.tasks.format]
+help = "Run all formatting tools against codebase"
+sequence = ["format-black", "format-prettier"]
+
+[tool.poe.tasks.format-black]
+help = "Run black against Python source code"
+cmd = "black --check --line-length 100 ."
+
+[tool.poe.tasks.format-prettier]
+help = "Run prettier against non-Python code"
+cmd = "npx --yes prettier@3.0.3 . --no-config --check"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"

tests/e2e/test_cli.py

@@ -12,7 +12,7 @@
 
 
 def test_cli_default() -> None:
-    output = os.popen("poetry run package-name").read()
+    output = os.popen("package-name").read()
 
     assert output == (
         "usage: package-name [-h] [--version] [--zen]\n\n"
@@ -25,14 +25,14 @@ def test_cli_default() -> None:
 
 
 def test_cli_zen_flag() -> None:
-    output = os.popen("poetry run package-name --zen").read()
+    output = os.popen("package-name --zen").read()
 
     assert output.endswith(".\n"), "should return zen sentence"
     assert "usage" not in output, "should not print usage"
 
 
 def test_cli_version_flag() -> None:
-    output = os.popen("poetry run package-name --version").read()
+    output = os.popen("package-name --version").read()
 
     match = re.match(SEMVAR_PATTERN, output.strip())
     assert match is not None, "should print a semvar-compliant version"