feat(tests): add integration tests to tutor paragon plugin

plugins/tutor-contrib-paragon/Makefile

@@ -22,12 +22,15 @@ isort: ##  Sort imports. This target is not mandatory because the output may be
 	isort --skip=templates ${SRC_DIRS}
 
 unittest: ## Run code tests cases
-	pytest tests
+	pytest tests --ignore=tests/integration
+
+integration-test: ## Run integration tests cases
+	pytest tests/integration --order-scope=module
 
 dev-requirements: ## Install dev requirements
 	pip install -e .[dev]
 
-run-tests: test unittest  # Run static analysis and unit tests
+run-tests: test unittest integration-test  # Run all tests: static analysis, unit tests, and integration tests
 
 ESCAPE = 
 help: ## Print this help

plugins/tutor-contrib-paragon/README.rst

@@ -44,7 +44,6 @@ This structure is optimized for design token–based themes (see `Paragon Design
 
 .. note::
 
-   Documentation for how to use extensions is not yet available.
    A link to the official Open edX or Paragon documentation will be added here once it is published.
 
 Configuration
@@ -60,9 +59,92 @@ All configuration variables can be overridden via `tutor config save`:
       - theme-1
       - theme-2
     PARAGON_SERVE_COMPILED_THEMES: true
+    PARAGON_BUILDER_IMAGE: "paragon-builder:latest"
 
 You may customize paths or theme names to suit your deployment.
 
+Usage
+*****
+
+Prerequisites
+-------------
+
+- A built Paragon CLI image:
+
+  .. code-block:: bash
+
+      tutor images build paragon-builder
+
+- The ``PARAGON_THEME_SOURCES_PATH`` directory structured as follows:
+
+  .. code-block:: text
+
+      <PARAGON_THEME_SOURCES_PATH>/
+      ├── core/
+      │   └── ... (token files)
+      └── themes/
+          ├── light/     # example theme variant
+          │   └── ... (light theme token files)
+          └── dark/      # example theme variant
+          └── ... (dark theme token files)
+
+  In this structure:
+
+  - The ``core/`` directory contains base design tokens common across all themes.
+  - The ``themes/`` directory contains subdirectories for each theme variant (e.g., ``light``, ``dark``), each with tokens specific to that theme.
+
+Building Themes
+---------------
+
+Invoke the build process via Tutor:
+
+.. code-block:: bash
+
+    tutor local do paragon-build-tokens [OPTIONS]
+
+For more information about available options, refer to the `Paragon CLI documentation <https://github.com/openedx/paragon/?tab=readme-ov-file#paragon-cli>`__.
+
+Examples
+--------
+
+.. code-block:: bash
+
+  # Compile all themes listed in PARAGON_ENABLED_THEMES
+  tutor local do paragon-build-tokens
+
+  # Compile only specific themes
+  tutor local do paragon-build-tokens --themes theme-1,theme-2
+
+  # Pass any other Paragon CLI options as needed
+  tutor local do paragon-build-tokens --paragon-option value
+
+Output
+------
+
+Artifacts will be written to the directory specified by ``PARAGON_COMPILED_THEMES_PATH`` (default: ``env/plugins/paragon/compiled-themes``).
+
+Troubleshooting
+***************
+
+- **No custom themes built or only default tokens generated**  
+  Ensure that your custom theme directories exist under ``PARAGON_THEME_SOURCES_PATH`` and that their names exactly match those in ``PARAGON_ENABLED_THEMES`` or passed via ``--themes``. If no custom tokens are found, Paragon will fall back to its built-in defaults.
+
+- **Themes are not picked up when using --themes:**  
+  The value for ``--themes`` must be a comma-separated list (no spaces), e.g. ``--themes theme-1,theme-2``.
+
+- **Write permission denied**  
+  Verify that Docker and the Tutor process have write access to the path defined by ``PARAGON_COMPILED_THEMES_PATH``. Adjust filesystem permissions if necessary.
+
+- **Error: "Expected at least 4 args"**  
+  This occurs when the build job is invoked directly inside the container. Always run via Tutor:
+
+  .. code-block:: bash
+
+      tutor local do paragon-build-tokens [OPTIONS]
+
+- **Other issues**  
+  Re-run the build with ``--verbose`` to obtain detailed logs and identify misconfigurations or missing files.
+
 License
 *******
 

plugins/tutor-contrib-paragon/pyproject.toml

@@ -30,7 +30,7 @@ dependencies = [
     "tutor>=19.0.0,<20.0.0",
 ]
 
-optional-dependencies = { dev = ["tutor[dev]>=19.0.0,<20.0.0", "pytest>=8.3.4"] }
+optional-dependencies = { dev = ["tutor[dev]>=19.0.0,<20.0.0", "pytest>=8.3.4", "pytest-order>=1.3.0"] }
 
 # These fields will be set by hatch_build.py
 dynamic = ["version"]

plugins/tutor-contrib-paragon/tests/integration/conftest.py

@@ -0,0 +1,35 @@
+"""Common fixtures for integration tests."""
+
+import pytest
+import subprocess
+
+from .helpers import PARAGON_NAME, PARAGON_IMAGE
+
+
+@pytest.fixture(scope="package", autouse=True)
+def setup_tutor_paragon_plugin():
+    """
+    Fixture to set up the Tutor Paragon plugin for integration tests.
+    This fixture enables the Paragon plugin, builds the necessary Docker image,
+    and ensures that the plugin is disabled after the tests are complete.
+    """
+
+    subprocess.run(
+        ["tutor", "plugins", "enable", PARAGON_NAME],
+        check=True,
+        capture_output=True,
+    )
+
+    subprocess.run(
+        ["tutor", "images", "build", PARAGON_IMAGE],
+        check=True,
+        capture_output=True,
+    )
+
+    yield
+
+    subprocess.run(
+        ["tutor", "plugins", "disable", PARAGON_NAME],
+        check=True,
+        capture_output=True,
+    )

plugins/tutor-contrib-paragon/tests/integration/helpers.py

@@ -0,0 +1,54 @@
+"""Helper functions for integration tests of Paragon plugin."""
+
+import subprocess
+import logging
+
+logger = logging.getLogger(__name__)
+
+PARAGON_NAME = "paragon"
+PARAGON_IMAGE = "paragon-builder"
+PARAGON_JOB = "paragon-build-tokens"
+PARAGON_THEME_SOURCES_FOLDER = "env/plugins/paragon/theme-sources"
+PARAGON_COMPILED_THEMES_FOLDER = "env/plugins/paragon/compiled-themes"
+
+
+def execute_tutor_command(command: list[str]):
+    """Run a Tutor command and return the result.
+
+    Args:
+        command (list[str]): List of Tutor args, without the 'tutor' prefix.
+
+    Returns:
+        subprocess.CompletedProcess: Contains stdout, stderr, returncode.
+    """
+    full_command = ["tutor"] + command
+    result = subprocess.run(
+        full_command,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+
+    if result.returncode != 0:
+        logger.error("Command failed: %s", " ".join(full_command))
+        logger.error("stderr: %s", result.stderr.strip())
+
+    return result
+
+
+def get_tutor_root_path():
+    """Get the root path of the Tutor project.
+
+    Raises:
+        RuntimeError: If the Tutor root path cannot be obtained.
+
+    Returns:
+        str: The path to the Tutor root directory.
+    """
+    result = execute_tutor_command(["config", "printroot"])
+
+    if result.returncode != 0:
+        raise RuntimeError("Failed to get Tutor root path: " + result.stderr)
+
+    return result.stdout.strip()

plugins/tutor-contrib-paragon/tests/integration/plugin_functionality_test.py

@@ -0,0 +1,147 @@
+"""
+Integration tests for the Tutor Paragon plugin functionality.
+
+This module contains tests to verify that the Paragon plugin for Tutor
+is functioning correctly, including building tokens with and without options,
+and handling invalid flags or parameters.
+"""
+
+import os
+import shutil
+import pytest
+import re
+
+from .helpers import (
+    execute_tutor_command,
+    get_tutor_root_path,
+    PARAGON_JOB,
+    PARAGON_COMPILED_THEMES_FOLDER,
+)
+
+
+@pytest.fixture(autouse=True)
+def clear_compiled_themes_folder():
+    """
+    Fixture to clear the PARAGON_COMPILED_THEMES_FOLDER after each test.
+    """
+    yield
+    tutor_root = get_tutor_root_path()
+    compiled_path = os.path.join(tutor_root, PARAGON_COMPILED_THEMES_FOLDER)
+    if os.path.exists(compiled_path):
+        shutil.rmtree(compiled_path)
+
+
+@pytest.mark.order(1)
+def test_build_tokens_without_options():
+    """
+    Verify that running the build-tokens job without additional options
+    completes successfully and produces output in the compiled-themes folder.
+    """
+
+    result = execute_tutor_command(["local", "do", PARAGON_JOB])
+    assert result.returncode == 0, f"Error running build-tokens job: {result.stderr}"
+
+    tutor_root = get_tutor_root_path()
+    compiled_path = os.path.join(tutor_root, PARAGON_COMPILED_THEMES_FOLDER)
+
+    contents = os.listdir(compiled_path)
+    assert contents, f"No files were generated in {compiled_path}."
+
+
+@pytest.mark.order(2)
+def test_build_tokens_with_specific_theme():
+    """
+    Verify that running the build-tokens job with the --themes option
+    for a specific theme (e.g., 'indigo') produces the expected output.
+    """
+    theme = "indigo"
+
+    result = execute_tutor_command(["local", "do", PARAGON_JOB, "--themes", theme])
+    assert result.returncode == 0, f"Error building {theme} theme: {result.stderr}"
+
+    tutor_root = get_tutor_root_path()
+    compiled_path = os.path.join(tutor_root, PARAGON_COMPILED_THEMES_FOLDER, "themes")
+
+    entries = os.listdir(compiled_path)
+    assert theme in entries, f"'{theme}' theme not found in {compiled_path}."
+
+    theme_path = os.path.join(compiled_path, theme)
+    assert os.path.isdir(theme_path), f"Expected {theme_path} to be a directory."
+    assert os.listdir(theme_path), f"No files were generated inside {theme_path}."
+
+
+@pytest.mark.order(3)
+def test_build_tokens_excluding_core():
+    """
+    Verify that running the build-tokens job with the --exclude-core option
+    excludes the core theme from the output.
+    """
+    result = execute_tutor_command(["local", "do", PARAGON_JOB, "--exclude-core"])
+    assert result.returncode == 0, f"Error excluding core theme: {result.stderr}"
+
+    tutor_root = get_tutor_root_path()
+    compiled_path = os.path.join(tutor_root, PARAGON_COMPILED_THEMES_FOLDER)
+
+    entries = os.listdir(compiled_path)
+    assert "core" not in entries, "Core theme should be excluded but was found."
+
+
+@pytest.mark.order(4)
+def test_build_tokens_without_output_token_references():
+    """
+    Ensure that when the build-tokens job is run with --output-references=false,
+    the generated variables.css file does not contain any CSS variable references (var(--...)).
+    """
+    result = execute_tutor_command(
+        ["local", "do", PARAGON_JOB, "--output-references=false"]
+    )
+    assert (
+        result.returncode == 0
+    ), f"Error running build-tokens with --output-references=false: {result.stderr}"
+
+    tutor_root = get_tutor_root_path()
+    compiled_path = os.path.join(tutor_root, PARAGON_COMPILED_THEMES_FOLDER)
+
+    core_variables_css = os.path.join(compiled_path, "core", "variables.css")
+    theme_variables_css = os.path.join(compiled_path, "themes", "light", "variables.css")
+
+    assert os.path.exists(core_variables_css), f"{core_variables_css} does not exist."
+    assert os.path.exists(theme_variables_css), f"{theme_variables_css} does not exist."
+
+    with open(core_variables_css, "r", encoding="utf-8") as f:
+        core_content = f.read()
+    with open(theme_variables_css, "r", encoding="utf-8") as f:
+        theme_content = f.read()
+
+    token_reference_pattern = re.compile(r"var\(--.*?\)")
+    core_references = token_reference_pattern.findall(core_content)
+    theme_references = token_reference_pattern.findall(theme_content)
+
+    assert (
+        not core_references
+    ), f"{core_variables_css} should not contain token references, but found: {core_references}"
+    assert (
+        not theme_references
+    ), f"{theme_variables_css} should not contain token references, but found: {theme_references}"
+
+
+@pytest.mark.order(5)
+def test_build_tokens_with_source_tokens_only():
+    """
+    Ensure that when the build-tokens job is run with --source-tokens-only,
+    the utility-classes.css file is not generated.
+    """
+    result = execute_tutor_command(["local", "do", PARAGON_JOB, "--source-tokens-only"])
+    assert (
+        result.returncode == 0
+    ), f"Error running build-tokens with --source-tokens-only: {result.stderr}"
+
+    tutor_root = get_tutor_root_path()
+    light_theme_path = os.path.join(
+        tutor_root, PARAGON_COMPILED_THEMES_FOLDER, "themes", "light"
+    )
+    utility_classes_css = os.path.join(light_theme_path, "utility-classes.css")
+
+    assert not os.path.exists(
+        utility_classes_css
+    ), f"{utility_classes_css} should not exist when --source-tokens-only is used."