test: Documented conftest.py

Makefile

@@ -18,6 +18,11 @@ lint:  ## Lint and static-check
 	python -m flake8 apio
 	python -m pylint apio
 
+lint-test: ### Lint test scripts
+	python -m pylint test/conftest.py
+
+test-one:  ## Execute a test script
+	pytest -v -s test/test_apio.py::test_apio
 
 tox:   ## Run tox
 	python -m tox
@@ -32,5 +37,5 @@ install:  ## Install the tool locally
 	flit build
 	flit install
 
-tests: ## Make tests
+tests: ## Execute ALL the tests
 	pytest apio test

test/conftest.py

@@ -1,39 +1,95 @@
-# -*- coding: utf-8 -*-
+"""
+Pytest 
+TEST configuration file
+"""
+
+# os.environ: Access to environment variables
+#   https://docs.python.org/3/library/os.html#os.environ
+from os import environ
+from pathlib import Path
 
 import pytest
-from os import environ, getcwd, path
+
+# -- Class for executing click commands
+# https://click.palletsprojects.com/en/8.1.x/api/#click.testing.CliRunner
 from click.testing import CliRunner
 
+#-- Class for storing the results of executing a click command
+# https://click.palletsprojects.com/en/8.1.x/api/#click.testing.Result
+from click.testing import Result
+
+# -- Debug mode on/off
+DEBUG = True
+
 
 @pytest.fixture(scope='module')
 def clirunner():
+    """Return a special oject for executing a click cli command"""
     return CliRunner()
 
 
-@pytest.fixture(scope='session')
-def validate_cliresult():
-    def decorator(result):
-        assert result.exit_code == 0
-        assert not result.exception
-        assert 'error' not in result.output.lower()
-    return decorator
-
-
 @pytest.fixture(scope='session')
 def configenv():
+    """Return a function for configuring the apio test environment
+       By default it is tested in a temporaly folder (in /tmp/xxxxx)
+    """
     def decorator():
-        cwd = path.join(getcwd(), ' ñ')
+        # -- Set a strange directory for executing
+        # -- apio: it contains spaces and unicode characters
+        # -- for testing. It should work
+        cwd = str(Path.cwd() / ' ñ')
+
+        #-- Debug
+        if DEBUG:
+            print("")
+            print("  --> configenv():")
+            print(f"      apio working directory: {cwd}")
+
+        #-- Set the apio home dir and apio packages dir to
+        #-- this test folder
         environ['APIO_HOME_DIR'] = cwd
         environ['APIO_PKG_DIR'] = cwd
         environ['TESTING'] = ''
+
     return decorator
 
 
-def pytest_addoption(parser):
+@pytest.fixture(scope='session')
+def validate_cliresult():
+    """Return a function for Checking if a given click command 
+       has executed ok
+    """
+
+    def decorator(result : Result):
+        """Check if the result is ok"""
+
+        #-- It should return an exit code of 0: success
+        assert result.exit_code == 0
+
+        #-- There should be no exceptions raised
+        assert not result.exception
+
+        #-- The word 'error' should NOT appear on the standard output
+        assert 'error' not in result.output.lower()
+
+    return decorator
+
+
+#-- More info: https://docs.pytest.org/en/7.1.x/example/simple.html
+def pytest_addoption(parser:pytest.Parser):
+    """Register the --offline command line option when invoking pytest
+    """
+
+    #-- Option: --offline
+    #-- It is used by the function test that requieres
+    #-- internet connnection for testing
     parser.addoption('--offline', action='store_true',
                      help='Run tests in offline mode')
 
 
 @pytest.fixture
 def offline(request):
+    """Return the value of the offline parameter, given by the user
+       when calling pytest
+    """
     return request.config.getoption('--offline')

test/test_apio.py

@@ -1,14 +1,33 @@
+# -----------------------------------------------------------------------
+# - Tests for command "apio"
+#-- 
+#-- RUN manually:
+#--   pytest -v test/test_apio.py
+#--
+#-- DEBUG: if you want to add print traces for debuggin, execute this:
+#--   pytest -v -s test/test_apio.py
+#--
+#-- ONLY ONE TEST: You can invoke only one test funcion:
+#--    For example, it will only execute the test_apio() function
+#--   pytest -v -s test/test_apio.py::test_apio
+#------------------------------------------------------------------------    
+
+# -- Import the cli entry point: apio/__main__.py
+from click.testing import CliRunner
 from apio.__main__ import cli as cmd_apio
 
 
-def test_apio(clirunner, validate_cliresult, configenv):
+def test_apio(clirunner: CliRunner, validate_cliresult, configenv):
+
     with clirunner.isolated_filesystem():
         configenv()
         result = clirunner.invoke(cmd_apio)
+        print(result)
+        print(f"{result.exit_code=}")
         validate_cliresult(result)
 
 
-def test_apio_wrong_command(clirunner, validate_cliresult, configenv):
+def test_apio_wrong_command(clirunner: CliRunner, validate_cliresult, configenv):
     with clirunner.isolated_filesystem():
         configenv()
         result = clirunner.invoke(cmd_apio, ['missing_command'])