✅ [open-zaak/open-zaak#1649] Tests for generate envvar docs

testapp/settings.py

@@ -1,10 +1,34 @@
 from pathlib import Path
 
+from open_api_framework.conf.utils import config
+
 BASE_DIR = Path(__file__).resolve(strict=True).parent
 
-SECRET_KEY = "so-secret-i-cant-believe-you-are-looking-at-this"
+SECRET_KEY = config(
+    "SECRET_KEY",
+    "so-secret-i-cant-believe-you-are-looking-at-this",
+    group="Required",
+    help_text=("Secret key that's used for certain cryptographic utilities."),
+)
+DEBUG = config(
+    "DEBUG",
+    default=False,
+    help_text=(
+        "Only set this to ``True`` on a local development environment. "
+        "Various other security settings are derived from this setting!"
+    ),
+)
+IS_HTTPS = config(
+    "IS_HTTPS",
+    default=not DEBUG,
+    help_text=(
+        "Used to construct absolute URLs and controls a variety of security settings. "
+        "Defaults to the inverse of ``DEBUG``."
+    ),
+    auto_display_default=False,
+)
 
-USE_TZ = True
+USE_TZ = config("USE_TZ", True, add_to_docs=False)
 
 DATABASES = {
     "default": {
@@ -50,3 +74,7 @@
 ]
 
 ROOT_URLCONF = "testapp.urls"
+
+# These are excluded from generate_envvar_docs test by their group
+VARIABLE_TO_BE_EXCLUDED = config("VARIABLE_TO_BE_EXCLUDED1", "foo", group="Excluded")
+VARIABLE_TO_BE_EXCLUDED = config("VARIABLE_TO_BE_EXCLUDED2", "bar", group="Excluded")

tests/test_config_helpers.py

@@ -2,12 +2,12 @@
 
 
 def test_empty_list_as_default():
-    value = config("SOME_TEST_ENVVAR", split=True, default=[])
+    value = config("SOME_TEST_ENVVAR", split=True, default=[], add_to_docs=False)
 
     assert value == []
 
 
 def test_non_empty_list_as_default():
-    value = config("SOME_TEST_ENVVAR", split=True, default=["foo"])
+    value = config("SOME_TEST_ENVVAR", split=True, default=["foo"], add_to_docs=False)
 
     assert value == ["foo"]

tests/test_generate_envvar_docs.py

@@ -0,0 +1,82 @@
+from unittest.mock import mock_open, patch
+
+from django.core.management import call_command
+
+EXPECTED_OUTPUT = """\
+.. _installation_env_config:
+
+===================================
+Environment configuration reference
+===================================
+
+
+
+Available environment variables
+===============================
+
+
+Required
+--------
+
+* ``SECRET_KEY``: Secret key that's used for certain cryptographic utilities. Defaults to: ``so-secret-i-cant-believe-you-are-looking-at-this``.
+
+
+Optional
+--------
+
+* ``DEBUG``: Only set this to ``True`` on a local development environment. Various other security settings are derived from this setting!. Defaults to: ``False``.
+* ``IS_HTTPS``: Used to construct absolute URLs and controls a variety of security settings. Defaults to the inverse of ``DEBUG``.
+
+
+
+
+
+Specifying the environment variables
+=====================================
+
+There are two strategies to specify the environment variables:
+
+* provide them in a ``.env`` file
+* start the component processes (with uwsgi/gunicorn/celery) in a process
+  manager that defines the environment variables
+
+Providing a .env file
+---------------------
+
+This is the most simple setup and easiest to debug. The ``.env`` file must be
+at the root of the project - i.e. on the same level as the ``src`` directory (
+NOT *in* the ``src`` directory).
+
+The syntax is key-value:
+
+.. code::
+
+   SOME_VAR=some_value
+   OTHER_VAR="quoted_value"
+
+
+Provide the envvars via the process manager
+-------------------------------------------
+
+If you use a process manager (such as supervisor/systemd), use their techniques
+to define the envvars. The component will pick them up out of the box.
+"""
+
+
+def test_generate_envvar_docs():
+    mock_file = mock_open()
+    with patch(
+        "open_api_framework.management.commands.generate_envvar_docs.open", mock_file
+    ):
+        call_command(
+            "generate_envvar_docs", file="some/file/path.txt", exclude_group="Excluded"
+        )
+
+        mock_file.assert_called_once_with("some/file/path.txt", "w")
+
+        handle = mock_file()
+
+        # Check the entire content written to the mock file
+        written_content = "".join(call.args[0] for call in handle.write.call_args_list)
+
+        assert written_content == EXPECTED_OUTPUT