test local worktree with pytest by default

Enable pytest `pythonpath=src` by default to run tests against the local
worktree (e.g. when invoked via `poe test`).
An alternative task `poe gh-test` is added, which explicitly unsets
`pythonpath` in order to test the installed package (run in CI within
`uv` environment).

Author: thorsten-klein

.github/workflows/test.yml

@@ -19,13 +19,16 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
-        task: [test]
+        task: [gh-test]
         # The include map here is actually used to extend the matrix.
         # By passing all keys used in the matrix we append new unique combinations.
         # For more information see:
         # https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#example-adding-configurations
         include:
           # Run linter/type checks only on 1 combination
+          - os: ubuntu-latest
+            python-version: '3.13'
+            task: test
           - os: ubuntu-latest
             python-version: '3.13'
             task: gh-lint
@@ -61,15 +64,15 @@ jobs:
         run: uv run --frozen --directory "./check out/" --env-file=.github/http_env_block.conf poe ${{ matrix.task }}
 
       - name: Upload coverage reports
-        if: ${{ matrix.task == 'test' }}
+        if: ${{ matrix.task == 'gh-test' }}
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: coverage-${{ matrix.os }}-${{ matrix.python-version }}
           path: "./check out/.coverage"
           include-hidden-files: true
 
       - name: Upload test reports
-        if: ${{ matrix.task == 'test' }}
+        if: ${{ matrix.task == 'gh-test' }}
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: tests-${{ matrix.os }}-${{ matrix.python-version }}

README.rst

@@ -147,29 +147,31 @@ First, install the dependencies::
   # Recommended in an active virtual environment
   pip3 install --group dev
 
-Then, run the test suite locally from the top level directory::
 
-  # Using uv
+Then, run the tests (from the project's top level directory)::
+
+  # Run the full test suite with uv (recommended)
   uv run poe all
 
-  # Using poe
-  # Recommended in an active virtual environment
+  # Or run the full test suite with poe directly.
+  # (recommended in an active virtual environment)
   poe all
 
-  # Manually (test the installed west version)
+  # Run only the pytest tests (against the local worktree)
   pytest
 
-  # Manually (test the local copy)
-  pytest -o pythonpath=src
+The ``all`` target from ``poe`` runs multiple tasks sequentially. Use ``poe -h``
+to get a list of all available tasks.
+You can pass arguments to any ``poe`` task, which are forwarded to the
+underlying command. This is especially helpful when you want to run
+only specific tests to save time. Examples::
 
-The ``all`` target from ``poe`` runs multiple tasks sequentially. Run ``poe -h``
-to get the list of configured tasks.
-You can pass arguments to the task running ``poe``. This is especially useful
-on specific tests and save time. Examples::
-
-  # Run a subset of tests
+  # Run a subset of tests (file)
   poe test tests/test_project.py
 
+  # Run a single test
+  poe test tests/test_project.py::test_workspace
+
   # Run the ``test_update_narrow()`` code with ``pdb`` (but _not_ the
   # west code which is running in subprocesses)
   poe test --exitfirst --trace -k test_update_narrow

pyproject.toml

@@ -110,10 +110,16 @@ preview = true
 mypy_path = "src"
 ignore_missing_imports = true
 
+[tool.pytest.ini_options]
+# You can override any pytest option via pytest argument `-o key=value`.
+# E.g. unset option `-o pythonpath=` to use the installed west in tests
+pythonpath = "src"
+
 [tool.poe.tasks.test]
-cmd = "python -m pytest -v -W error --junitxml=junit.xml -o junit_family=xunit1 --cov-report=html --cov-config=pyproject.toml --cov=west"
+cmd = "python -m pytest -W error"
 env = {PYTHONIOENCODING = "utf-8"}
 
+
 [tool.poe.tasks]
 lint = "ruff check ."
 format = "ruff format"
@@ -126,3 +132,7 @@ all = ["test", "lint", "format", "types"]
 # Github specific tasks
 gh-lint = "ruff check --output-format=github ."
 gh-format = "ruff format --check --output-format=github"
+
+[tool.poe.tasks.gh-test]
+cmd = "python -m pytest -W error -v -o pythonpath= -o junit_family=xunit1 --junitxml=junit.xml --cov-report=html --cov-config=pyproject.toml --cov=west"
+env = {PYTHONIOENCODING = "utf-8"}