Merge pull request #309 from RSE-Sheffield/feat/test-frontend

Add frontend testing framework

Author: Joe-Heffer-Shef

.github/workflows/django-check.yaml

@@ -25,6 +25,7 @@ jobs:
           # This should match the version used in production
           node-version: 'v20.x'
           cache: 'npm'
+          cache-dependency-path: 'package-lock.json'
       - name: Install JavaScript package
         run: |
           npm ci

.github/workflows/lint-typescript.yaml

@@ -1,28 +1,36 @@
 # ESLint is a static code analysis tool for finding problems with ECMAScript/JavaScript code
 # https://eslint.org/
-name: Lint JavaScript code
+name: Lint & test JavaScript code
 on:
   push:
-    branches: [  "dev" ]
-  pull_request:
     branches: [ "dev" ]
+  pull_request:
+    branches: [ "dev", "main" ]
+permissions:
+  contents: read
+  pull-requests: write  # post coverage reports
 jobs:
-  build:
+  test:
     runs-on: ubuntu-24.04
     steps:
-    - name: Checkout
-      uses: actions/[email protected]
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: 'v20.x'
-        cache: 'npm'
-        cache-dependency-path: 'package-lock.json'
-    - run: npm ci
-    # https://eslint.org/docs/latest/use/command-line-interface
-    # We also need the Svelte linter https://sveltejs.github.io/eslint-plugin-svelte/
-    # This could be improved by using a configuration file
-    # https://eslint.org/docs/latest/use/configure/configuration-files#configuration-file
-    - name: Run ESLint
-      working-directory: .
-      run: npm run lintjs
+      - name: Checkout
+        uses: actions/[email protected]
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: 'package.json'
+          cache-dependency-path: 'package-lock.json'
+      - run: npm ci
+      # https://eslint.org/docs/latest/use/command-line-interface
+      # We also need the Svelte linter https://sveltejs.github.io/eslint-plugin-svelte/
+      # This could be improved by using a configuration file
+      # https://eslint.org/docs/latest/use/configure/configuration-files#configuration-file
+      - name: Run linter
+        run: npm run lint
+      - name: Run test suite
+        run: npm run test:coverage
+      - name: Report coverage
+        uses: davelosert/[email protected]
+        with:
+          json-summary-path: ui_components/coverage/coverage-summary.json
+          json-final-path: ui_components/coverage/coverage-final.json

SORT/__init__.py

@@ -0,0 +1 @@
+from SORT.checks import *

SORT/checks/README.md

@@ -0,0 +1,6 @@
+# Django system checks
+
+See: [System check framework](https://docs.djangoproject.com/en/5.2/topics/checks/) in the Django documentation.
+
+To activate a system check, import it to `SORT/checks/__init__.py` and append the function name to the `__all__` list.
+This will ensure the check is registered when the application is initialised.

SORT/checks/__init__.py

@@ -0,0 +1,4 @@
+from .vite_manifest import check_manifest
+from .survey_config import check_survey_config
+
+__all__ = ["check_manifest", "check_survey_config"]

SORT/checks/survey_config.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+from django.core.checks import Tags, Error
+import django.conf
+import django.contrib.staticfiles.finders
+
+settings = django.conf.settings
+
+SURVEY_CONFIG_FILE_PATHS = {
+    "data/survey_config/consent_only_config.json",
+    "data/survey_config/demography_only_config.json"
+}
+
+
+@django.core.checks.register(Tags.staticfiles)
+def check_survey_config(*args, **kwargs) -> list[Error]:
+    """
+    Ensure that survey configuration files exist
+    """
+    errors = list()
+
+    for path in SURVEY_CONFIG_FILE_PATHS:
+        path = Path(path).absolute()
+        if not path.exists():
+            errors.append(
+                Error(f"File not found: {path}", hint="Make sure the survey config file is present.")
+            )
+
+    return errors

SORT/checks/vite_manifest.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+import django.core.checks
+import django.conf
+import django.contrib.staticfiles.finders
+
+settings = django.conf.settings
+
+
+@django.core.checks.register(django.core.checks.Tags.staticfiles)
+def check_manifest(*args, **kwargs) -> list[django.core.checks.Error]:
+    """
+    Ensure that the Vite manifest file is present.
+    https://vite.dev/guide/backend-integration
+
+    This is a Django system check:
+    https://docs.djangoproject.com/en/5.2/topics/checks/
+    """
+    errors = list()
+
+    # Check the settings is specified
+    if not getattr(settings, 'VITE_MANIFEST_FILE_PATH', None):
+        errors.append(
+            django.core.checks.Error(
+                f"Setting not defined VITE_MANIFEST_FILE_PATH",
+                hint="Add VITE_MANIFEST_FILE_PATH to settings.py",
+                id="SORT.E001",
+            ),
+        )
+
+    # Find the manifest.json file in the static folder
+    path = django.contrib.staticfiles.finders.find(settings.VITE_MANIFEST_FILE_PATH)
+
+    # Check if manifest.json is present
+    if not path:
+        absolute_path = Path(settings.STATIC_ROOT).joinpath(settings.VITE_MANIFEST_FILE_PATH).absolute()
+        errors.append(
+            django.core.checks.Error(
+                f"File not found: '{absolute_path}'",
+                hint="Ensure that the JavaScript project has been built (npm run build)",
+                id="SORT.E002",
+            ),
+        )
+
+    return errors

SORT/settings.py

@@ -213,11 +213,12 @@ def cast_to_boolean(obj: Any) -> bool:
 AUTH_USER_MODEL = "home.User"  # FA: replace username with email as unique identifiers
 
 # Vite integration
-VITE_BASE_URL = "http://localhost:5173"  # Url of vite dev server
-VITE_STATIC_DIR = (
-    "ui-components"  # Path to vite-generated asset directory in the static folder
-)
-VITE_MANIFEST_FILE_PATH = os.path.join(VITE_STATIC_DIR, "manifest.json")
+if DEBUG:
+    VITE_BASE_URL = "http://localhost:5173"
+    "URL of Vite local development server"
+VITE_STATIC_DIR = "ui-components"
+"Path to vite-generated asset directory in the static folder"
+VITE_MANIFEST_FILE_PATH = Path(os.path.join(VITE_STATIC_DIR, "manifest.json"))
 
 X_FRAME_OPTIONS = "SAMEORIGIN"
 
@@ -281,4 +282,4 @@ def cast_to_boolean(obj: Any) -> bool:
 ACCOUNT_SIGNUP_FIELDS = ["email*", "password1*", "password2*"]
 ACCOUNT_LOGIN_METHODS = {"email"}
 ACCOUNT_USER_MODEL_USERNAME_FIELD = None
-ACCOUNT_EMAIL_VERIFICATION="mandatory"
+ACCOUNT_EMAIL_VERIFICATION = "mandatory"

docs/testing.md

@@ -1,19 +1,49 @@
 # SORT testing
 
+There are two testing frameworks in place: one for the frontend (JavaScript and Node.js) and another for the backend (Python Django).
+
+# Frontend testing
+
+## Usage
+
+To run the test suite, use the `test` command via the Node package manager (NPM):
+
+```bash
+npm test
+```
+
+This will execute Vitest. There are also other testing modes. To run the tests whenever the code changes using a file watcher, run:
+
+```bash
+npm run test:watch
+```
+
+And to get a coverage report:
+
+```bash
+npm run test:coverage
+```
+
+## Writing tests
+
+The frontend tests are contained in the `ui_components/tests` directory and are organised to match the source code structure. Each test should test an isolated unit of code. Please read the [introduction to writing tests for Svelte](https://svelte.dev/docs/svelte/testing) and the [Svelte testing library](https://testing-library.com/docs/svelte-testing-library/intro).
+
+# Backend testing
+
 The test suite uses the Django testing tools. For more information, please read [Testing in Django](https://docs.djangoproject.com/en/5.1/topics/testing/) and
 the further [Django testing examples](https://django-testing-docs.readthedocs.io/en/latest/index.html).
 
-# Installation
+## Installation
 
 To install the necessary packages in your local development environment, use the `requirements-dev.txt` file.
 
 ```bash
 pip install --upgrade --requirement requirements-dev.txt
 ```
 
-# Usage
+## Usage
 
-## Running the test suite
+### Running the test suite
 
 Pleaser read the [running tests](https://docs.djangoproject.com/en/5.1/topics/testing/overview/#running-tests) section of the Django documentation.
 
@@ -22,22 +52,22 @@ python manage.py test home/tests --parallel=auto --failfast
 python manage.py test survey/tests --parallel=auto --failfast
 ```
 
-## Coverage reports
+### Coverage reports
 
 At the end of the GitHub Actions testing workflow, a coverage report will be generated using the [Coverage.py](https://coverage.readthedocs.io/) tool.
 
-# Writing tests
+## Writing tests
 
 Please read the Django [writing tests section](https://docs.djangoproject.com/en/5.1/topics/testing/overview/#writing-tests) of the Django documentation. There are unit tests in the `./tests` directory of each Django application.
 
-## Tests
+### Tests
 
 The tests are defined in each application in the `tests` directory, where each file is a Python script that contains tests for a different aspect of the app. The filenames must start with `test_`.
 
-## Test cases
+### Test cases
 
 There are test case classes defined in the [`SORT.test.test_case`](SORT/test/test_case) module that contain useful methods for testing Django views and the application service layer in the SORT code.
 
-## Object factories
+### Object factories
 
 There are factory utilities that are used to create mock objects of our Django models for testing in the [`SORT.test.model_factory`](SORT/test/model_factory) module. This uses the [Factory Boy](https://factoryboy.readthedocs.io/en/stable/index.html) library, which [supports the Django ORM](https://factoryboy.readthedocs.io/en/stable/orms.html#module-factory.django).

home/templatetags/vite_integration.py

@@ -1,6 +1,7 @@
 import json
 import logging
 from enum import Enum
+from pathlib import Path
 from os import path
 from typing import LiteralString
 from urllib.parse import urljoin
@@ -51,11 +52,12 @@ def vite_asset(asset_path: str) -> str:
     else:
         global VITE_MANIFEST
         if VITE_MANIFEST is None:
-            vite_manifest_path = finders.find(settings.VITE_MANIFEST_FILE_PATH)
+            vite_manifest_path = Path(finders.find(settings.VITE_MANIFEST_FILE_PATH))
             if vite_manifest_path:
-                with open(vite_manifest_path, "r") as f:
-                    VITE_MANIFEST = json.load(f)
+                with vite_manifest_path.open() as file:
+                    VITE_MANIFEST = json.load(file)
             else:
+                logger.error("File not found: %s", vite_manifest_path)
                 raise FileNotFoundError(
                     f"Vite manifest file ({settings.VITE_MANIFEST_FILE_PATH}) cannot be found."
                 )
@@ -85,7 +87,7 @@ def vite_asset(asset_path: str) -> str:
 
 
 def get_asset_import_tag(
-    asset_static_path: str | LiteralString | bytes, type: AssetType
+        asset_static_path: str | LiteralString | bytes, type: AssetType
 ):
     asset_static_path_found = finders.find(asset_static_path)
     if asset_static_path_found: