Add tests and test directories to PYTHONPATH in basilisp test CLI command (#1326)

Fixes #1069

Author: chrisrink10

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Changed
+ * Add `test` and `tests` directories to `PYTHONPATH` automatically during `basilisp test` CLI invocations (#1069)
 
 ## [v0.5.0]
 ### Added
@@ -777,6 +779,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Basilisp language and compiler base.
 
+[Unreleased]: https://github.com/basilisp-lang/basilisp/compare/v0.5.0..HEAD
 [v0.5.0]: https://github.com/basilisp-lang/basilisp/compare/v0.4.0..v0.5.0
 [v0.4.0]: https://github.com/basilisp-lang/basilisp/compare/v0.3.8..v0.4.0
 [v0.3.8]: https://github.com/basilisp-lang/basilisp/compare/v0.3.7..v0.3.8

docs/cli.rst

@@ -205,6 +205,10 @@ If you installed the `PyTest <https://docs.pytest.org/en/7.0.x/>`_ extra, you ca
 
 Because Basilisp defers all testing logic to PyTest, you can use any standard PyTest arguments and flags from this entrypoint.
 
+.. seealso::
+
+   :ref:`testing`
+
 .. _bootstrap_cli_command:
 
 Bootstrap Python Installation

docs/gettingstarted.rst

@@ -73,6 +73,25 @@ If you believe you have discovered a bug, please review the :ref:`Contributing G
 Using Basilisp in a Project
 ---------------------------
 
+.. _project_template:
+
+Project Template
+^^^^^^^^^^^^^^^^
+
+Basilisp has a `Leiningen project template <https://github.com/basilisp-lang/lein-template-basilisp>`_ which can be used to create a new project.
+
+.. code-block::
+
+   lein new org.basilisp/basilisp myproject
+
+The template uses ``pip`` as the default dependency management tool.
+This is not meant to be prescriptive, but rather to enable users to get setup with minimum effort since most Python installations ship with ``pip`` by default.
+The generated project works with ``uv`` without any changes.
+
+.. note::
+
+   The template handles :ref:`bootstrapping` for you.
+
 .. _project_structure:
 
 Project Structure
@@ -89,7 +108,6 @@ Basilisp source files should always have a ``.lpy`` extension.
 
    .
    ├── README.md
-   ├── poetry.lock
    ├── pyproject.toml
    ├── src
    │   └── myproject
@@ -108,7 +126,7 @@ Basilisp source files should always have a ``.lpy`` extension.
    A single ``__init__.py`` file may be required for running tests with Pytest -- see :ref:`testing_path` for more information.
 
 Basilisp apps can use any of Python's myriad dependency management options, such as `pip <https://pip.pypa.io/en/stable/>`_, `uv <https://docs.astral.sh/uv/>`_, `Poetry <https://python-poetry.org/>`_, and many others.
-Basilisp itself uses Poetry and that is the recommended dependency management tool for new Basilisp projects.
+Basilisp itself uses Poetry.
 
 .. _bootstrapping:
 

docs/testing.rst

@@ -86,7 +86,7 @@ In this case, the test namespace can start at ``myproject``:
    (ns myproject.core-test)
 
 
-However, the ``test`` directory must be explicitly added to the ``PYTHONPATH`` using the ``--include-path`` (or ``-p``) option when running the tests:
+However, the ``test`` directory must be explicitly added to the ``PYTHONPATH`` using the ``--include-path`` (or ``-p`` or the ``PYTHONPATH`` environment variable) option when running the tests:
 
 .. code-block:: shell
 
@@ -99,6 +99,14 @@ However, the ``test`` directory must be explicitly added to the ``PYTHONPATH`` u
    In the first example above (``tests``, a Python convention), the top-level directory is already in the ``PYTHONPATH``, allowing ``tests.myproject.core-test`` to be resolvable.
    In the second example (``test``, a Clojure convention), the test directory is explicitly added to the ``PYTHONPATH``, enabling ``myproject.core-test`` to be resolvable.
 
+.. warning::
+
+   In versions of Basilisp prior to v0.5.1, you will also want to specify ``--include-unsafe-path=false`` to disable Python prepending the empty string ``""`` (meaning the current directory) to the path.
+   Without this, PyTest will attempt to collect your namespace from ``./test`` first, which will attempt to import your test namespaces as ``test.{namespace}``, which will fail collection.
+
+   After version v0.5.1, ``basilisp test`` automatically prepends ``tests`` and ``test`` (if either exist) to the ``PYTHONPATH``.
+   You can disable this behavior by passing ``--include-default-test-path=false`` or ``-d false``.
+
 .. _test_settings:
 
 Test Settings

src/basilisp/cli.py

@@ -324,7 +324,9 @@ def _add_debug_arg_group(parser: argparse.ArgumentParser) -> None:
     )
 
 
-def _add_import_arg_group(parser: argparse.ArgumentParser) -> None:
+def _add_import_arg_group(
+    parser: argparse.ArgumentParser, include_unsafe_path_default: bool = True
+) -> None:
     group = parser.add_argument_group(
         "path options",
         description=(
@@ -336,14 +338,16 @@ def _add_import_arg_group(parser: argparse.ArgumentParser) -> None:
         "--include-unsafe-path",
         action="store",
         nargs="?",
-        const=True,
-        default=os.getenv("BASILISP_INCLUDE_UNSAFE_PATH", "true"),
+        const=include_unsafe_path_default,
+        default=os.getenv(
+            "BASILISP_INCLUDE_UNSAFE_PATH", str(include_unsafe_path_default)
+        ),
         type=_to_bool,
         help=(
             "if true, automatically prepend a potentially unsafe path to `sys.path`; "
             "setting `--include-unsafe-path=false` is the Basilisp equivalent to "
             "setting PYTHONSAFEPATH to a non-empty string for CPython's REPL "
-            "(env: BASILISP_INCLUDE_UNSAFE_PATH; default: true)"
+            f"(env: BASILISP_INCLUDE_UNSAFE_PATH; default: {str(include_unsafe_path_default).lower()})"
         ),
     )
     group.add_argument(
@@ -732,12 +736,23 @@ def test(
     args: argparse.Namespace,
     extra: list[str],
 ) -> None:  # pragma: no cover
+    # Add `test` or `tests` directory to the current working directory
+    if args.include_default_test_path:
+        if not getattr(args, "include_path", []):
+            args.include_path = []
+        for d in ("tests", "test"):
+            p = Path.cwd() / d
+            if p.exists():
+                args.include_path.append(str(p))
+
     init_path(args)
     basilisp.init(_compiler_opts(args))
+
     # parse_known_args leaves the `--` separator as the first element if it is present
     # but retaining that causes PyTest to interpret all the arguments as positional
     if extra and extra[0] == "--":
         extra = extra[1:]
+
     try:
         import pytest
     except (ImportError, ModuleNotFoundError):
@@ -784,8 +799,23 @@ def test(
     allows_extra=True,
 )
 def _add_test_subcommand(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "-d",
+        "--include-default-test-path",
+        action="store",
+        nargs="?",
+        const=True,
+        default=os.getenv("BASILISP_INCLUDE_DEFAULT_TEST_PATH", "true"),
+        type=_to_bool,
+        help=(
+            "if true, automatically prepend a 'test' or 'tests' directory to the "
+            "PYTHONPATH enabling discovery and importing of test namespaces "
+            "(env: BASILISP_INCLUDE_DEFAULT_TEST_PATH; default: true)"
+        ),
+    )
+
     _add_compiler_arg_group(parser)
-    _add_import_arg_group(parser)
+    _add_import_arg_group(parser, include_unsafe_path_default=False)
     _add_runtime_arg_group(parser)
     _add_debug_arg_group(parser)
 

tests/basilisp/testrunner_test.py

@@ -271,7 +271,7 @@ def test_basilisp_test_noargs(pytester: pytest.Pytester):
     runtime.Namespace.remove(sym.symbol("a.test-path"))
 
     code = """
-    (ns tests.test-path
+    (ns test-path
       (:require
        [basilisp.test :refer [deftest is]]))
     (deftest passing-test