Staging

.github/workflows/test.yml

@@ -197,15 +197,15 @@ jobs:
 
   # ====================== BACKEND TESTS ======================
   test-backend:
-    name: Test Backend (shard ${{ matrix.shard }}/4)
+    name: Test Backend (shard ${{ matrix.shard }}/2)
     runs-on: ubuntu-latest
     needs: detect-changes
     if: needs.detect-changes.outputs.backend == 'true'
 
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2, 3, 4]
+        shard: [1, 2]
 
     services:
       postgres:
@@ -221,6 +221,7 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
+          --shm-size=256mb
 
     steps:
       - name: Checkout repository
@@ -258,10 +259,10 @@ jobs:
         uses: actions/cache/restore@v4
         with:
           path: backend/.test_durations
-          key: test-durations-${{ github.sha }}-${{ matrix.shard }}
+          key: test-durations-v2-${{ github.sha }}-${{ matrix.shard }}
           restore-keys: |
-            test-durations-combined-
-            test-durations-
+            test-durations-v2-combined-
+            test-durations-v2-
         continue-on-error: true
 
       - name: Run tests with coverage
@@ -284,7 +285,7 @@ jobs:
           EMAIL_PORT: "25"
         run: |
           poetry run pytest \
-            --splits 4 \
+            --splits 2 \
             --group ${{ matrix.shard }} \
             --store-durations \
             -n auto \
@@ -316,7 +317,7 @@ jobs:
         uses: actions/cache/save@v4
         with:
           path: backend/.test_durations
-          key: test-durations-${{ github.sha }}-${{ matrix.shard }}
+          key: test-durations-v2-${{ github.sha }}-${{ matrix.shard }}
 
       - name: Upload coverage data
         uses: actions/upload-artifact@v4

README.md

@@ -6,7 +6,18 @@
 ![Backend Coverage](https://img.shields.io/badge/backend--coverage-83%25-green)
 
 
-A comprehensive project management system for scientific research projects, developed by the Department of Biodiversity, Conservation and Attractions (DBCA), Western Australia.
+A project management and approval system for scientific research projects.
+
+## Key Features
+
+- **Annual Report Generation** - PDF generation of annual reports with customisable templates (key deliverable)
+- **Rich Text Editor** - Bespoke editor for project documentation with formatting and media support
+- **Document Management** - Project wizard with related document generation and PDF export capabilities
+- **Caretaker System** - Workflow for temporary project ownership delegation with approval processes
+- **Email Notifications** - Automated notifications for project updates, tasks, and approvals workflow
+- **Team Collaboration** - Manage internal teams, external collaborators, and stakeholder relationships
+- **Role-Based Access Control** - Granular permissions for different user types and project roles
+- **Audit Trails** - Complete history of all project changes and activities
 
 ## Quick Start
 

backend/README.md

@@ -1,9 +1,5 @@
 # Science Projects Management System (SPMS) Backend
 
-[![Tests](https://github.com/dbca-wa/science-projects/actions/workflows/ci.yml/badge.svg)](https://github.com/dbca-wa/science-projects/actions/workflows/ci.yml)
-[![Backend Coverage](https://raw.githubusercontent.com/dbca-wa/science-projects/badges/backend-coverage.svg)](https://github.com/dbca-wa/science-projects/actions)
-[![CodeQL](https://github.com/dbca-wa/science-projects/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/dbca-wa/science-projects/actions/workflows/github-code-scanning/codeql)
-[![Issues](https://img.shields.io/static/v1?label=docs&message=Issues&color=brightgreen)](https://github.com/dbca-wa/science-projects/issues)
 
 > **Note**: This is the backend component of the Science Projects monorepo. See the [root README](../README.md) for the complete system overview.
 
@@ -192,21 +188,118 @@ See [Feature Development](../documentation/backend/development/feature-developme
 
 ## Testing
 
+### Quick Start
+
 ```bash
-# Run all tests
+# Fast feedback - unit tests only (26 seconds)
+poetry run pytest -m unit
+
+# Integration tests (44 seconds)
+poetry run pytest -m integration
+
+# Full test suite (68 seconds)
 poetry run pytest
 
-# Run with coverage
+# With coverage report
+poetry run pytest --cov=. --cov-report=html
+```
+
+### Test Categories
+
+Tests are organised into three categories using pytest markers:
+
+**Unit Tests** (`@pytest.mark.unit`):
+- Pure Python logic, no database
+- Serializer validation
+- Utility functions
+- Fast execution (< 30 seconds total)
+
+**Integration Tests** (`@pytest.mark.integration`):
+- View tests with database
+- Service layer tests
+- API endpoint tests
+- Medium execution (< 2 minutes total)
+
+**Slow Tests** (`@pytest.mark.slow`):
+- Complex workflows
+- Multi-model transactions
+- Admin action tests
+- Slower execution (< 3 minutes total)
+
+### Running Specific Test Categories
+
+```bash
+# Unit tests only - fastest feedback
+poetry run pytest -m unit
+
+# Integration tests only
+poetry run pytest -m integration
+
+# Slow tests only
+poetry run pytest -m slow
+
+# All except slow tests
+poetry run pytest -m "not slow"
+
+# Specific app with category
+poetry run pytest users/tests/ -m unit
+```
+
+### Development Workflow
+
+**During Development** (rapid iteration):
+```bash
+poetry run pytest -m unit  # 26 seconds
+```
+
+**Before Committing** (thorough validation):
+```bash
+poetry run pytest -m integration  # 44 seconds
+```
+
+**Before Pushing** (final check):
+```bash
+poetry run pytest  # 68 seconds
+```
+
+### Coverage Reports
+
+Coverage reports are available in `htmlcov/index.html` after running tests with coverage:
+
+```bash
+# Generate coverage report
 poetry run pytest --cov=. --cov-report=html
 
+# Open in browser
+open htmlcov/index.html  # macOS
+xdg-open htmlcov/index.html  # Linux
+```
+
+### Additional Test Options
+
+```bash
 # Run specific app tests
 poetry run pytest agencies/tests/
 
-# Run in parallel
+# Run in parallel (faster)
 poetry run pytest -n auto
+
+# Verbose output
+poetry run pytest -v
+
+# Stop on first failure
+poetry run pytest -x
+
+# Show test durations
+poetry run pytest --durations=10
 ```
 
-Coverage reports are available in `htmlcov/index.html` after running tests with coverage.
+### Test Documentation
+
+For detailed testing guidelines, see:
+- [Testing Guidelines](docs/testing/guidelines.md) - Comprehensive guide
+- [Marker Reference](docs/testing/markers.md) - Complete marker documentation
+- [Performance Report](docs/testing/performance-report.md) - Optimization metrics
 
 ## Code Quality