Write unit test suite

.coveragerc

@@ -0,0 +1,16 @@
+# Coverage report configuration
+# https://coverage.readthedocs.io/en/7.7.1/config.html
+
+[run]
+source = .
+omit =
+    __init__.py
+    */migrations/*
+    SORT/*
+    */admin.py
+    */tests/*
+
+[report]
+format = markdown
+skip_empty = true
+sort = Cover

.github/workflows/check-gunicorn-config.yaml

@@ -14,6 +14,7 @@ jobs:
       - name: Setup Python
         uses: actions/[email protected]
         with:
+          # This should match the version used in production
           python-version: "3.12"
           cache: "pip"
       - name: Install dependencies

.github/workflows/django-check.yaml

@@ -5,7 +5,8 @@ on:
   pull_request:
     branches: [ "main", "dev" ]
 jobs:
-  lint:
+  django-test:
+    name: Run Django automated checks and tests
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
@@ -15,12 +16,19 @@ jobs:
         with:
           # This should match the version used in production
           python-version: "3.12"
+          cache: "pip"
       - name: Install dependencies
+        run: pip install --requirement requirements.txt --requirement requirements-dev.txt
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          # This should match the version used in production
+          node-version: 'v20.x'
+          cache: 'npm'
+      - name: Install JavaScript package
         run: |
-          # Update pip
-          python -m pip install --upgrade pip
-          # https://pip.pypa.io/en/stable/cli/pip_install/
-          pip install --requirement requirements.txt
+          npm ci
+          npm run build
       # https://docs.djangoproject.com/en/5.1/ref/django-admin/#check
       - name: Run Django system checks
         run: |
@@ -30,4 +38,13 @@ jobs:
       - name: Run Django test suites
         run: |
           export DJANGO_SECRET_KEY="$(python -c "import secrets; print(secrets.token_urlsafe())")"
-          python manage.py test
+          # Iterate over Django apps with test directories
+          for test_dir in **/tests
+          do
+            echo "Testing $test_dir"
+            # https://docs.djangoproject.com/en/5.1/topics/testing/advanced/#integration-with-coverage-py
+            coverage run --source="home,survey" manage.py test "$test_dir" --verbosity=2 --parallel=auto
+          done
+          # Generate coverage report
+          echo "## Coverage report" >> $GITHUB_STEP_SUMMARY
+          coverage report --format="markdown" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -38,11 +38,12 @@ pip-log.txt
 pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+.coverage
 
 # Django stuff:
 *.log
 local_settings.py
-db.sqlite3
+*.sqlite3
 
 # Sphinx documentation
 

CONTRIBUTING.md

@@ -12,10 +12,16 @@ Please use the [Kanban board](https://github.com/orgs/RSE-Sheffield/projects/19)
 
 ## Proposing changes
 
-1. [Raise an issue](https://github.com/RSE-Sheffield/SORT/issues/new?template=Blank+issue) clearly describing the problem or user requirements;
-2. [Create a branch](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-a-branch-for-an-issue) that is associated with that issue. It can be helpful to prefix the branch name to match the type of changes e.g. `feat/123-my-feature` for features or `docs/my-guide` for documentation, etc. See [Semantic branch names](https://damiandabrowski.medium.com/semantic-branch-names-and-commit-messages-3ac38a6fcbb6).
+1. [Raise an issue](https://github.com/RSE-Sheffield/SORT/issues/new?template=Blank+issue) clearly describing the
+   problem or user requirements;
+2. [Create a branch](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-a-branch-for-an-issue)
+   that is associated with that issue. It can be helpful to prefix the branch name to match the type of changes
+   e.g. `feat/123-my-feature` for features or `docs/my-guide` for documentation, etc.
+   See [Semantic branch names](https://damiandabrowski.medium.com/semantic-branch-names-and-commit-messages-3ac38a6fcbb6).
 3. In that branch, make changes that aim to resolve that issue;
-4. Create a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) (PR) while the changes are being designed;
+4. Create
+   a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) (
+   PR) while the changes are being designed;
 5. When ready, mark the PR "Ready for review" and request for reviewers to look at the proposed changes;
 
 ## Environments
@@ -25,6 +31,15 @@ There are two main environments:
 - Development (the `dev` branch and the `sort-web-dev` virtual machine)
 - Production (the `main` branch and the `sort-web-app` virtual machine)
 
+### Local development environment
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install --editable .
+pip install -r requirements-dev.txt
+```
+
 ## Change process
 
 Any proposed changes should be proposed in pull requests that would be merged into the `dev` branch.
@@ -63,3 +78,7 @@ gitGraph
 # Code of Conduct
 
 We expect all contributors to follow the SORT [Code of Conduct](CODE_OF_CONDUCT.md).
+
+# Testing
+
+Please read the [testing documentation](docs/testing.md).

README.md

@@ -98,20 +98,36 @@ Please read [`docs/deployment.md`](docs/deployment.md).
 
 
 # Vite integration
-The SORT app uses some javascript components such as the survey configurator and the survey response form. This is
-implemented using the svelte framework and vite is used as the bundler. Vite also provides a live server for 
-development which includes HMR (hot module reloading).
+The SORT app uses some JavaScript components such as the survey configurator and the survey response form. This is
+implemented using the svelte framework and vite is used as the bundler. [Vite](https://vite.dev/) also provides a live server for development which includes HMR (hot module reloading).
 
-In order to integrate this into the html template, a tag library is created at `/home/templatetags/vite_integration.py`.
-- The `vite_client` template tag is used to include Vite's HMR javascript code. 
-- The `vite_asset` tag is used to include asset files (e.g. typescript files) in the template.
-  - In debug mode, this creates a link directly to the vite dev server normally located at `http://localhost:5173`
-  - In production mode, it links to assets within the  `/static/` url path. 
+In order to integrate this into the HTML template, a [custom template tag](https://docs.djangoproject.com/en/5.1/howto/custom-template-tags/) library is created at `/home/templatetags/vite_integration.py`.
+- The `vite_client` template tag is used to include Vite's HMR JavaScript code. 
+- The `vite_asset` tag is used to include asset files (e.g. TypeScript files) in the template.
+  - In debug mode, this creates a link directly to the Vite dev server normally located at `http://localhost:5173`
+  - In production mode, the link changes to the location of the file in the `/static/` folder
 
+For more information, please [read the README](ui-components/README.md).
+
+## Installation
+
+Install the JavaScript package using [`npm install`](https://docs.npmjs.com/cli/v8/commands/npm-install/)
+
+```bash
+npm install
+```
+
+## Usage
+
+The development mode will run the test page at http://localhost:5173
+
+```bash
+npm run dev
+```
 
 ## Before deployment
 
-The script files within `/ui_components` must be built into the static folder before deployment. This
+The script files within `./ui_components/` must be built into the static folder before deployment. This
 can be done by running:
 
 ```bash

SORT/settings.py

@@ -33,7 +33,7 @@ def cast_to_boolean(obj: Any) -> bool:
 
 
 # Load environment variables from .env file
-load_dotenv(os.getenv("DJANGO_ENV_PATH"))
+load_dotenv(dotenv_path=os.getenv("DJANGO_ENV_PATH", ".env"))
 
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = Path(__file__).resolve().parent.parent
@@ -53,25 +53,28 @@ def cast_to_boolean(obj: Any) -> bool:
 ALLOWED_HOSTS = os.getenv("DJANGO_ALLOWED_HOSTS", "sort-web-app.shef.ac.uk").split()
 
 # Application definition
-
 INSTALLED_APPS = [
     "django.contrib.admin",
     "django.contrib.auth",
     "django.contrib.contenttypes",
     "django.contrib.sessions",
     "django.contrib.messages",
     "django.contrib.staticfiles",
+    # Plugins
     "django_bootstrap5",
     "django_extensions",
-    "debug_toolbar",
     "qr_code",
     "crispy_forms",
     "crispy_bootstrap5",
-    # apps created by FA:
+    # SORT apps
     "home",
     "survey",
 ]
 
+if DEBUG:
+    # https://django-debug-toolbar.readthedocs.io/en/latest/installation.html
+    INSTALLED_APPS.append("debug_toolbar")
+
 MIDDLEWARE = [
     # Implement security in the web server, not in Django.
     # https://docs.djangoproject.com/en/5.1/ref/middleware/#module-django.middleware.security
@@ -82,8 +85,9 @@ def cast_to_boolean(obj: Any) -> bool:
     "django.contrib.auth.middleware.AuthenticationMiddleware",
     "django.contrib.messages.middleware.MessageMiddleware",
     "django.middleware.clickjacking.XFrameOptionsMiddleware",
-    "debug_toolbar.middleware.DebugToolbarMiddleware",
 ]
+if DEBUG:
+    MIDDLEWARE.append("debug_toolbar.middleware.DebugToolbarMiddleware")
 
 ROOT_URLCONF = "SORT.urls"
 
@@ -207,10 +211,6 @@ def cast_to_boolean(obj: Any) -> bool:
 )
 VITE_MANIFEST_FILE_PATH = os.path.join(VITE_STATIC_DIR, "manifest.json")
 
-# FA: for production:
-
-# EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
-
 X_FRAME_OPTIONS = "SAMEORIGIN"
 
 # File uploading

SORT/test/model_factory/README.md

@@ -0,0 +1,4 @@
+# Model factories
+
+Create dummy objects and fixtures for testing using [Factory Boy](https://factoryboy.readthedocs.io/en/stable/) which [supports the Django ORM](https://factoryboy.readthedocs.io/en/stable/orms.html#module-factory.django).
+

SORT/test/model_factory/__init__.py

@@ -0,0 +1,8 @@
+from .organisation import OrganisationFactory
+from .project import ProjectFactory
+from .survey import SurveyFactory
+from .user import UserFactory, SuperUserFactory
+from .invitation import InvitationFactory
+
+__all__ = ["InvitationFactory", "UserFactory", "SuperUserFactory", "SurveyFactory", "OrganisationFactory",
+           "ProjectFactory"]

SORT/test/model_factory/invitation.py

@@ -0,0 +1,11 @@
+import factory.django
+
+from survey.models import Invitation
+from .survey import SurveyFactory
+
+
+class InvitationFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Invitation
+
+    survey = factory.SubFactory(SurveyFactory)

SORT/test/model_factory/organisation.py

@@ -0,0 +1,19 @@
+import factory.django
+
+from home.models import Organisation
+from .organisation_membership import OrganisationMembershipFactory
+
+from home.constants import ROLE_ADMIN
+
+
+class OrganisationFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Organisation
+        django_get_or_create = ("name",)
+
+    name = factory.Sequence(lambda n: f"Organisation {n}")
+    description = factory.Sequence(lambda n: f"Organisation description {n}")
+    # Create an administrator user
+    # https://factoryboy.readthedocs.io/en/stable/recipes.html#reverse-dependencies-reverse-foreignkey
+    members = factory.RelatedFactory(OrganisationMembershipFactory, factory_related_name="organisation",
+                                     role=ROLE_ADMIN)

SORT/test/model_factory/organisation_membership.py

@@ -0,0 +1,11 @@
+import factory.django
+
+from home.models import OrganisationMembership
+from .user import UserFactory
+
+
+class OrganisationMembershipFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = OrganisationMembership
+
+    user = factory.SubFactory(UserFactory, first_name="Admin User")

SORT/test/model_factory/project.py

@@ -0,0 +1,13 @@
+import factory.django
+
+from .organisation import OrganisationFactory
+from home.models import Project
+
+
+class ProjectFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Project
+
+    name = factory.Sequence(lambda n: f"Project {n}")
+    description = factory.Sequence(lambda n: f"Project description {n}")
+    organisation = factory.SubFactory(OrganisationFactory)

SORT/test/model_factory/survey.py

@@ -0,0 +1,14 @@
+import factory.django
+
+from SORT.test.model_factory import ProjectFactory
+from survey.models import Survey
+
+
+class SurveyFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Survey
+        django_get_or_create = ("name", "description")
+
+    name = factory.Sequence(lambda n: f"Survey {n}")
+    description = factory.Sequence(lambda n: f"Survey description {n}")
+    project = factory.SubFactory(ProjectFactory)

SORT/test/model_factory/user/__init__.py

@@ -0,0 +1,4 @@
+from .user import UserFactory
+from .superuser import SuperUserFactory
+
+__all__ = ['UserFactory', 'SuperUserFactory']

SORT/test/model_factory/user/constants.py

@@ -0,0 +1,3 @@
+import secrets
+
+PASSWORD = secrets.token_urlsafe()

SORT/test/model_factory/user/superuser.py

@@ -0,0 +1,8 @@
+import factory
+from .user import UserFactory
+
+
+class SuperUserFactory(UserFactory):
+    is_superuser = True
+    first_name = factory.Sequence(lambda n: f"Superuser{n}")
+    email = factory.Sequence(lambda n: f"superuser{n}@sort.com")

SORT/test/model_factory/user/user.py

@@ -0,0 +1,14 @@
+import django.contrib.auth
+import factory
+from .constants import PASSWORD
+
+
+class UserFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = django.contrib.auth.get_user_model()
+        django_get_or_create = ("email",)
+
+    email = factory.Sequence(lambda n: f"user{n}@sort.com")
+    first_name = factory.Sequence(lambda n: f"User{n}")
+    last_name = factory.Sequence(lambda n: f"Lastname{n}")
+    password = factory.PostGenerationMethodCall("set_password", PASSWORD)

SORT/test/test_case/__init__.py

@@ -0,0 +1,4 @@
+from .service import ServiceTestCase
+from .view import ViewTestCase
+
+__all__ = ["ViewTestCase", "ServiceTestCase"]

SORT/test/test_case/base.py

@@ -0,0 +1,13 @@
+import django.test
+
+from ..model_factory import UserFactory, SuperUserFactory
+
+
+class SORTTestCase(django.test.TestCase):
+    """
+    A test case for testing the SORT web application.
+    """
+
+    def setUp(self):
+        self.user = UserFactory()
+        self.superuser = SuperUserFactory()

SORT/test/test_case/service.py

@@ -0,0 +1,18 @@
+"""
+A unit testing class for testing SORT application services.
+"""
+
+from typing import Optional
+from home.services.base import BasePermissionService
+
+from .base import SORTTestCase
+
+
+class ServiceTestCase(SORTTestCase):
+    """
+    A test case for testing an application service layer.
+    """
+
+    def setUp(self):
+        super().setUp()
+        self.service: Optional[BasePermissionService] = None