Add an empty entry to sys.path for basilisp test CLI subcommand (#1075)

Relates to #1069

Author: chrisrink10

CHANGELOG.md

@@ -9,11 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Added functions to `basilisp.test` for using and combining test fixtures (#980)
  * Added the `importing-resolve` function for dynamically importing and resolving a Python name (#1065, #1070)
  * Added support for highlighting matching parens, brackets, and braces at the REPL (#1074)
+ * Added the `-p`/`--include-path` argument to `basilisp test` CLI subcommand (#1075)
+ * Added an empty entry to `sys.path` for `basilisp test` CLI subcommand (#1075)
 
 ### Fixed
  * Fix a bug where the reader was double counting the CRLF newline seq in metadata (#1063)
  * Conform to the `cider-nrepl` `info` ops spec by ensuring result's `:file` is URI, also added missing :column number (#1066)
  * Fix a bug with `basilisp.edn/write-string` where nested double quotes were not escaped properly (#1071)
+ * Fix a bug where additional arguments to `basilisp test` CLI subcommand were not being passed correctly to Pytest (#1075)
 
 ## [v0.2.3]
 ### Added

docs/gettingstarted.rst

@@ -57,25 +57,27 @@ Sub or child namespaces may be nested using folders.
 A namespace may be both a "leaf" and "branch" node in the source tree without any special configuration, as ``myproject.pkg`` is below.
 Basilisp source files should always have a ``.lpy`` extension.
 
-::
+.. code-block:: text
 
    .
    ├── README.md
    ├── poetry.lock
    ├── pyproject.toml
    ├── src
-   │   └── myproject
-   │       ├── core.lpy
-   │       ├── pkg
-   │       │   └── subns.lpy
-   │       └── pkg.lpy
+   │   └── myproject
+   │       ├── core.lpy
+   │       └── pkg
+   │           └── subns.lpy
+   │           └── pkg.lpy
    └── tests
+       └── __init__.py
        └── myproject
            └── test_core.lpy
 
 .. note::
 
-   Python ``__init__.py`` files are not required anywhere in Basilisp projects (including for nested namespaces), though you may need to use them if your project mixes Python and Basilisp sources.
+   Python ``__init__.py`` files are not required anywhere in Basilisp project source directories (including for nested namespaces), though you may need to use them if your project mixes Python and Basilisp sources.
+   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, including `pip <https://pip.pypa.io/en/stable/>`_, `Pipenv <https://pipenv.pypa.io/en/latest/>`_, and `Poetry <https://python-poetry.org/>`_.
 Basilisp itself uses Poetry and that is the recommended dependency management tool for new Basilisp projects.

docs/testing.rst

@@ -36,6 +36,34 @@ For asserting repeatedly against different inputs, you can use the :lpy:fn:`are`
        4  2 2
        0 -1 1)
 
+.. _testing_path:
+
+Testing and ``PYTHONPATH``
+--------------------------
+
+Typical Clojure projects will have parallel ``src/`` and ``tests/`` folders in the project root.
+Project management tooling typically constructs the Java classpath to include both parallel trees for development and only ``src/`` for deployed software.
+Basilisp does not currently have such tooling (though it is planned!) and the recommended Python tooling is not configurable to allow for this distinction.
+
+Due to this limitation, the easiest solution to facilitate test discovery with Pytest (Basilisp's default test runner) is to include a single, empty ``__init__.py`` file in the top-level ``tests`` directory:
+
+.. code-block:: text
+
+   tests
+   ├── __init__.py
+   └── myproject
+       └── core_test.lpy
+
+Test namespaces can then be created as if they are part of a giant ``tests`` package:
+
+.. code-block::
+
+   (ns tests.myproject.core-test)
+
+.. note::
+
+   The project maintainers acknowledge that this is not an ideal solution and would like to provide a more Clojure-like solution in the future.
+
 .. _test_fixtures:
 
 Fixtures

src/basilisp/cli.py

@@ -7,7 +7,7 @@
 import textwrap
 import types
 from pathlib import Path
-from typing import Any, Callable, Optional, Sequence, Type
+from typing import Any, Callable, List, Optional, Sequence, Type, Union
 
 from basilisp import main as basilisp
 from basilisp.lang import compiler as compiler
@@ -379,7 +379,10 @@ def _add_runtime_arg_group(parser: argparse.ArgumentParser) -> None:
     )
 
 
-Handler = Callable[[argparse.ArgumentParser, argparse.Namespace], None]
+Handler = Union[
+    Callable[[argparse.ArgumentParser, argparse.Namespace], None],
+    Callable[[argparse.ArgumentParser, argparse.Namespace, List[str]], None],
+]
 
 
 def _subcommand(
@@ -388,6 +391,7 @@ def _subcommand(
     help: Optional[str] = None,  # pylint: disable=redefined-builtin
     description: Optional[str] = None,
     handler: Handler,
+    allows_extra: bool = False,
 ) -> Callable[
     [Callable[[argparse.ArgumentParser], None]],
     Callable[["argparse._SubParsersAction"], None],
@@ -400,6 +404,7 @@ def _wrapped_subcommand(subparsers: "argparse._SubParsersAction"):
                 subcommand, help=help, description=description
             )
             parser.set_defaults(handler=handler)
+            parser.set_defaults(allows_extra=allows_extra)
             f(parser)
 
         return _wrapped_subcommand
@@ -722,8 +727,11 @@ def _add_run_subcommand(parser: argparse.ArgumentParser) -> None:
 
 
 def test(
-    parser: argparse.ArgumentParser, args: argparse.Namespace
+    parser: argparse.ArgumentParser,
+    args: argparse.Namespace,
+    extra: List[str],
 ) -> None:  # pragma: no cover
+    init_path(args)
     basilisp.init(_compiler_opts(args))
     try:
         import pytest
@@ -732,18 +740,20 @@ def test(
             "Cannot run tests without dependency PyTest. Please install PyTest and try again.",
         )
     else:
-        pytest.main(args=list(args.args))
+        pytest.main(args=list(extra))
 
 
 @_subcommand(
     "test",
     help="run tests in a Basilisp project",
     description="Run tests in a Basilisp project.",
     handler=test,
+    allows_extra=True,
 )
 def _add_test_subcommand(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("args", nargs=-1)
+    parser.add_argument("args", nargs=-1, help="arguments passed on to Pytest")
     _add_compiler_arg_group(parser)
+    _add_import_arg_group(parser)
     _add_runtime_arg_group(parser)
     _add_debug_arg_group(parser)
 
@@ -765,7 +775,7 @@ def run_script():
     This is provided as a shim for platforms where shebang lines cannot contain more
     than one argument and thus `#!/usr/bin/env basilisp run` would be non-functional.
 
-    The current process is replaced as by `os.execlp`."""
+    The current process is replaced as by `os.execvp`."""
     # os.exec* functions do not perform shell expansion, so we must do so manually.
     script_path = Path(sys.argv[1]).resolve()
     args = ["basilisp", "run", str(script_path)]
@@ -790,9 +800,15 @@ def invoke_cli(args: Optional[Sequence[str]] = None) -> None:
     _add_test_subcommand(subparsers)
     _add_version_subcommand(subparsers)
 
-    parsed_args = parser.parse_args(args=args)
-    if hasattr(parsed_args, "handler"):
-        parsed_args.handler(parser, parsed_args)
+    parsed_args, extra = parser.parse_known_args(args=args)
+    allows_extra = getattr(parsed_args, "allows_extra", False)
+    if extra and not allows_extra:
+        parser.error(f"unrecognized arguments: {' '.join(extra)}")
+    elif hasattr(parsed_args, "handler"):
+        if allows_extra:
+            parsed_args.handler(parser, parsed_args, extra)
+        else:
+            parsed_args.handler(parser, parsed_args)
     else:
         parser.print_help()