update

README.MD

@@ -0,0 +1,72 @@
+# Employee Scheduling (Python)
+
+Schedule shifts to employees, accounting for employee availability and shift skill requirements.
+
+![Employee Scheduling Screenshot](./employee-scheduling-screenshot.png)
+
+- [Prerequisites](#prerequisites)
+- [Run the application](#run-the-application)
+- [Test the application](#test-the-application)
+
+> [!TIP]
+>  <img src="https://docs.timefold.ai/_/img/models/employee-shift-scheduling.svg" align="right" width="50px" /> [Check out our off-the-shelf model for Employee Shift Scheduling](https://app.timefold.ai/models/employee-scheduling/v1). This model supports many additional constraints such as skills, pairing employees, fairness and more.
+
+## Prerequisites
+
+1. Install [Python 3.11 or 3.12](https://www.python.org/downloads/).
+
+2. Install JDK 17+, for example with [Sdkman](https://sdkman.io):
+
+   ```sh
+   $ sdk install java
+   ```
+
+## Run the application
+
+1. Git clone the timefold-solver-python repo and navigate to this directory:
+
+   ```sh
+   $ git clone https://github.com/TimefoldAI/timefold-solver-python.git
+   ...
+   $ cd timefold-solver-python/quickstarts/employee-scheduling
+   ```
+
+2. Create a virtual environment:
+
+   ```sh
+   $ python -m venv .venv
+   ```
+
+3. Activate the virtual environment:
+
+   ```sh
+   $ . .venv/bin/activate
+   ```
+
+4. Install the application:
+
+   ```sh
+   $ pip install -e .
+   ```
+
+5. Run the application:
+
+   ```sh
+   $ run-app
+   ```
+
+6. Visit [http://localhost:8080](http://localhost:8080) in your browser.
+
+7. Click on the **Solve** button.
+
+## Test the application
+
+1. Run tests:
+
+   ```sh
+   $ pytest
+   ```
+
+## More information
+
+Visit [timefold.ai](https://timefold.ai).

src/employee_scheduling/.project

@@ -0,0 +1 @@
+/srv/lab/dev/solverforge/solverforge-quickstarts/fast/employee-scheduling-fast/src/employee_scheduling

src/employee_scheduling/__init__.py

@@ -1,6 +1,6 @@
 import uvicorn
 
-from .rest_api import app
+from .rest_api import app as app
 
 
 def main():

src/employee_scheduling/constraints.py

@@ -5,7 +5,7 @@ from solverforge_legacy.solver.score import (
     HardSoftDecimalScore,
     ConstraintCollectors,
 )
-from datetime import datetime, date
+from datetime import datetime, date, time
 
 from .domain import Employee, Shift
 
@@ -33,13 +33,12 @@ def overlapping_in_minutes(
 
 
 def get_shift_overlapping_duration_in_minutes(shift: Shift, dt: date) -> int:
-    overlap = 0
     start_date_time = datetime.combine(dt, datetime.min.time())
     end_date_time = datetime.combine(dt, datetime.max.time())
-    overlap += overlapping_in_minutes(
+    overlap = overlapping_in_minutes(
         start_date_time, end_date_time, shift.start, shift.end
     )
-    return overlap
+    return int(overlap)
 
 
 @constraint_provider
@@ -51,7 +50,7 @@ def define_constraints(constraint_factory: ConstraintFactory):
         at_least_10_hours_between_two_shifts(constraint_factory),
         one_shift_per_day(constraint_factory),
         unavailable_employee(constraint_factory),
-        max_shifts_per_employee(constraint_factory),
+        # max_shifts_per_employee(constraint_factory),  # Optional extension - disabled by default
         # Soft constraints
         undesired_day_for_employee(constraint_factory),
         desired_day_for_employee(constraint_factory),
@@ -126,10 +125,10 @@ def unavailable_employee(constraint_factory: ConstraintFactory):
             Joiners.equal(lambda shift: shift.employee, lambda employee: employee),
         )
         .flatten_last(lambda employee: employee.unavailable_dates)
-        .filter(lambda shift, unavailable_date: shift.is_overlapping_with_date(unavailable_date))
+        .filter(lambda shift, unavailable_date: is_overlapping_with_date(shift, unavailable_date))
         .penalize(
             HardSoftDecimalScore.ONE_HARD,
-            lambda shift, unavailable_date: shift.get_overlapping_duration_in_minutes(unavailable_date),
+            lambda shift, unavailable_date: int((min(shift.end, datetime.combine(unavailable_date, time(23, 59, 59))) - max(shift.start, datetime.combine(unavailable_date, time(0, 0, 0)))).total_seconds() / 60),
         )
         .as_constraint("Unavailable employee")
     )
@@ -169,7 +168,7 @@ def undesired_day_for_employee(constraint_factory: ConstraintFactory):
         .filter(lambda shift, undesired_date: shift.is_overlapping_with_date(undesired_date))
         .penalize(
             HardSoftDecimalScore.ONE_SOFT,
-            lambda shift, undesired_date: shift.get_overlapping_duration_in_minutes(undesired_date),
+            lambda shift, undesired_date: int((min(shift.end, datetime.combine(undesired_date, time(23, 59, 59))) - max(shift.start, datetime.combine(undesired_date, time(0, 0, 0)))).total_seconds() / 60),
         )
         .as_constraint("Undesired day for employee")
     )
@@ -186,7 +185,7 @@ def desired_day_for_employee(constraint_factory: ConstraintFactory):
         .filter(lambda shift, desired_date: shift.is_overlapping_with_date(desired_date))
         .reward(
             HardSoftDecimalScore.ONE_SOFT,
-            lambda shift, desired_date: shift.get_overlapping_duration_in_minutes(desired_date),
+            lambda shift, desired_date: int((min(shift.end, datetime.combine(desired_date, time(23, 59, 59))) - max(shift.start, datetime.combine(desired_date, time(0, 0, 0)))).total_seconds() / 60),
         )
         .as_constraint("Desired day for employee")
     )

src/employee_scheduling/converters.py

@@ -1,8 +1,5 @@
-from typing import List, Optional, Union
 from datetime import datetime, date
 from . import domain
-from .json_serialization import JsonDomainBase
-from pydantic import Field
 
 
 # Conversion functions from domain to API models

src/employee_scheduling/demo_data.py

@@ -5,7 +5,7 @@ from random import Random
 from typing import Generator
 from dataclasses import dataclass, field
 
-from .domain import *
+from .domain import Employee, EmployeeSchedule, Shift
 
 
 class DemoData(Enum):

src/employee_scheduling/rest_api.py

@@ -1,7 +1,8 @@
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
 from fastapi.staticfiles import StaticFiles
 from uuid import uuid4
 from dataclasses import replace
+from typing import Dict, List
 
 from .domain import EmployeeSchedule, EmployeeScheduleModel
 from .converters import (
@@ -9,6 +10,7 @@ from .converters import (
 )
 from .demo_data import DemoData, generate_demo_data
 from .solver import solver_manager, solution_manager
+from .score_analysis import ConstraintAnalysisDTO, MatchAnalysisDTO
 
 app = FastAPI(docs_url='/q/swagger-ui')
 data_sets: dict[str, EmployeeSchedule] = {}
@@ -48,9 +50,79 @@ async def solve_timetable(schedule_model: EmployeeScheduleModel) -> str:
     return job_id
 
 
+@app.get("/schedules")
+async def list_schedules() -> List[str]:
+    """List all job IDs of submitted schedules."""
+    return list(data_sets.keys())
+
+
+@app.get("/schedules/{problem_id}/status")
+async def get_status(problem_id: str) -> Dict:
+    """Get the schedule status and score for a given job ID."""
+    if problem_id not in data_sets:
+        raise ValueError(f"No schedule found with ID {problem_id}")
+
+    schedule = data_sets[problem_id]
+    solver_status = solver_manager.get_solver_status(problem_id)
+
+    return {
+        "score": {
+            "hardScore": schedule.score.hard_score if schedule.score else 0,
+            "softScore": schedule.score.soft_score if schedule.score else 0,
+        },
+        "solverStatus": solver_status.name,
+    }
+
+
 @app.delete("/schedules/{problem_id}")
-async def stop_solving(problem_id: str) -> None:
-    solver_manager.terminate_early(problem_id)
+async def stop_solving(problem_id: str) -> EmployeeScheduleModel:
+    """Terminate solving for a given job ID."""
+    if problem_id not in data_sets:
+        raise ValueError(f"No schedule found with ID {problem_id}")
+
+    try:
+        solver_manager.terminate_early(problem_id)
+    except Exception as e:
+        print(f"Warning: terminate_early failed for {problem_id}: {e}")
+
+    return await get_timetable(problem_id)
+
+
+@app.put("/schedules/analyze")
+async def analyze_schedule(request: Request) -> Dict:
+    """Submit a schedule to analyze its score."""
+    json_data = await request.json()
+
+    # Parse the incoming JSON using Pydantic models
+    schedule_model = EmployeeScheduleModel.model_validate(json_data)
+
+    # Convert to domain model for analysis
+    domain_schedule = model_to_schedule(schedule_model)
+
+    analysis = solution_manager.analyze(domain_schedule)
+
+    # Convert to proper DTOs for correct serialization
+    # Use str() for scores and justification to avoid Java object serialization issues
+    constraints = []
+    for constraint in getattr(analysis, 'constraint_analyses', []) or []:
+        matches = [
+            MatchAnalysisDTO(
+                name=str(getattr(getattr(match, 'constraint_ref', None), 'constraint_name', "")),
+                score=str(getattr(match, 'score', "0hard/0soft")),
+                justification=str(getattr(match, 'justification', "")),
+            )
+            for match in getattr(constraint, 'matches', []) or []
+        ]
+
+        constraint_dto = ConstraintAnalysisDTO(
+            name=str(getattr(constraint, 'constraint_name', "")),
+            weight=str(getattr(constraint, 'weight', "0hard/0soft")),
+            score=str(getattr(constraint, 'score', "0hard/0soft")),
+            matches=matches,
+        )
+        constraints.append(constraint_dto)
+
+    return {"constraints": [constraint.model_dump() for constraint in constraints]}
 
 
 app.mount("/", StaticFiles(directory="static", html=True), name="static")

src/employee_scheduling/score_analysis.py

@@ -0,0 +1,15 @@
+from pydantic import BaseModel
+from typing import List
+
+
+class MatchAnalysisDTO(BaseModel):
+    name: str
+    score: str
+    justification: str
+
+
+class ConstraintAnalysisDTO(BaseModel):
+    name: str
+    weight: str
+    score: str
+    matches: List[MatchAnalysisDTO]

static/app.js

@@ -440,12 +440,14 @@ function refreshSolvingButtons(solving) {
     if (solving) {
         $("#solveButton").hide();
         $("#stopSolvingButton").show();
+        $("#solvingSpinner").addClass("active");
         if (autoRefreshIntervalId == null) {
             autoRefreshIntervalId = setInterval(refreshSchedule, 2000);
         }
     } else {
         $("#solveButton").show();
         $("#stopSolvingButton").hide();
+        $("#solvingSpinner").removeClass("active");
         if (autoRefreshIntervalId != null) {
             clearInterval(autoRefreshIntervalId);
             autoRefreshIntervalId = null;

static/index.html

@@ -14,6 +14,24 @@
         .vis-time-axis .vis-grid.vis-sunday {
             background: #D3D7CFFF;
         }
+
+        /* Solving spinner */
+        #solvingSpinner {
+            display: none;
+            width: 1.25rem;
+            height: 1.25rem;
+            border: 2px solid #10b981;
+            border-top-color: transparent;
+            border-radius: 50%;
+            animation: spin 0.75s linear infinite;
+            vertical-align: middle;
+        }
+        #solvingSpinner.active {
+            display: inline-block;
+        }
+        @keyframes spin {
+            to { transform: rotate(360deg); }
+        }
     </style>
     <link rel="icon" href="/webjars/solverforge/img/solverforge-favicon.svg" type="image/svg+xml">
 </head>
@@ -38,8 +56,12 @@
             <button id="stopSolvingButton" type="button" class="btn btn-danger">
                 <span class="fas fa-stop"></span> Stop solving
             </button>
+            <span id="solvingSpinner" class="ms-2"></span>
             <span id="unassignedShifts" class="ms-2 align-middle fw-bold"></span>
             <span id="score" class="score ms-2 align-middle fw-bold">Score: ?</span>
+            <button id="analyzeButton" type="button" class="ms-2 btn btn-secondary">
+                <span class="fas fa-question"></span>
+            </button>
 
             <div class="float-end">
                 <ul class="nav nav-pills" role="tablist">
@@ -119,6 +141,24 @@
         </div>
     </div>
 </div>
+
+<div class="modal fadebd-example-modal-lg" id="scoreAnalysisModal" tabindex="-1" aria-labelledby="scoreAnalysisModalLabel" aria-hidden="true">
+    <div class="modal-dialog modal-lg modal-dialog-scrollable">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h1 class="modal-title fs-5" id="scoreAnalysisModalLabel">Score analysis <span id="scoreAnalysisScoreLabel"></span></h1>
+                <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+            </div>
+            <div class="modal-body" id="scoreAnalysisModalContent">
+                <!-- Filled in by app.js -->
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Close</button>
+            </div>
+        </div>
+    </div>
+</div>
+
 <footer id="solverforge-auto-footer"></footer>
 
 <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/2.11.8/umd/popper.min.js"></script>

static/webjars/timefold/css/timefold-webui.css

@@ -0,0 +1,60 @@
+:root {
+    /* Keep in sync with .navbar height on a large screen. */
+    --ts-navbar-height: 109px;
+
+    --ts-violet-1-rgb: #3E00FF;
+    --ts-violet-2-rgb: #3423A6;
+    --ts-violet-3-rgb: #2E1760;
+    --ts-violet-4-rgb: #200F4F;
+    --ts-violet-5-rgb: #000000; /* TODO FIXME */
+    --ts-violet-dark-1-rgb: #b6adfd;
+    --ts-violet-dark-2-rgb: #c1bbfd;
+    --ts-gray-rgb: #666666;
+    --ts-white-rgb: #FFFFFF;
+    --ts-light-rgb: #F2F2F2;
+    --ts-gray-border: #c5c5c5;
+
+    --tf-light-rgb-transparent: rgb(242,242,242,0.5); /* #F2F2F2 = rgb(242,242,242) */
+    --bs-body-bg: var(--ts-light-rgb); /* link to html bg */
+    --bs-link-color: var(--ts-violet-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-2-rgb);
+
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+    --bs-nav-link-font-size: 18px;
+    --bs-nav-link-font-weight: 400;
+    --bs-nav-link-color: var(--ts-white-rgb);
+    --ts-nav-link-hover-border-color: var(--ts-violet-1-rgb);
+}
+.btn {
+    --bs-btn-border-radius: 1.5rem;
+}
+.btn-primary {
+    --bs-btn-bg: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-2-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-2-rgb);
+    --bs-btn-active-bg: var(--ts-violet-2-rgb);
+    --bs-btn-active-border-bg: var(--ts-violet-2-rgb);
+    --bs-btn-disabled-bg: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.btn-outline-primary {
+    --bs-btn-color: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-1-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-active-bg: var(--ts-violet-1-rgb);
+    --bs-btn-active-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.navbar-dark {
+    --bs-link-color: var(--ts-violet-dark-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-dark-2-rgb);
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+}
+.nav-pills {
+    --bs-nav-pills-link-active-bg: var(--ts-violet-1-rgb);
+}

static/webjars/timefold/js/timefold-webui.js

@@ -0,0 +1,142 @@
+function replaceTimefoldAutoHeaderFooter() {
+  const timefoldHeader = $("header#timefold-auto-header");
+  if (timefoldHeader != null) {
+    timefoldHeader.addClass("bg-black")
+    timefoldHeader.append(
+      $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg navbar-dark shadow mb-3">
+          <a class="navbar-brand" href="https://timefold.ai">
+            <img src="/timefold/img/timefold-logo-horizontal-negative.svg" alt="Timefold logo" width="200">
+          </a>
+        </nav>
+      </div>`));
+  }
+  const timefoldFooter = $("footer#timefold-auto-footer");
+  if (timefoldFooter != null) {
+    timefoldFooter.append(
+      $(`<footer class="bg-black text-white-50">
+           <div class="container">
+             <div class="hstack gap-3 p-4">
+               <div class="ms-auto"><a class="text-white" href="https://timefold.ai">Timefold</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://timefold.ai/docs">Documentation</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://github.com/TimefoldAI/timefold-solver-python">Code</a></div>
+               <div class="vr"></div>
+               <div class="me-auto"><a class="text-white" href="https://timefold.ai/product/support/">Support</a></div>
+             </div>
+           </div>
+           <div id="applicationInfo" class="container text-center"></div>
+         </footer>`));
+
+      applicationInfo();
+  }
+
+}
+
+function showSimpleError(title) {
+    const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+        .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+        .append($(`<div class="toast-body"/>`)
+            .append($(`<p/>`).text(title))
+        );
+    $("#notificationPanel").append(notification);
+    notification.toast({delay: 30000});
+    notification.toast('show');
+}
+
+function showError(title, xhr) {
+  var serverErrorMessage = !xhr.responseJSON ? `${xhr.status}: ${xhr.statusText}` : xhr.responseJSON.message;
+  var serverErrorCode = !xhr.responseJSON ? `unknown` : xhr.responseJSON.code;
+  var serverErrorId = !xhr.responseJSON ? `----` : xhr.responseJSON.id;
+  var serverErrorDetails = !xhr.responseJSON ? `no details provided` : xhr.responseJSON.details;
+
+  if (xhr.responseJSON && !serverErrorMessage) {
+	  serverErrorMessage = JSON.stringify(xhr.responseJSON);
+	  serverErrorCode = xhr.statusText + '(' + xhr.status + ')';
+	  serverErrorId = `----`;
+  }
+
+  console.error(title + "\n" + serverErrorMessage + " : " + serverErrorDetails);
+  const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+    .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+    .append($(`<div class="toast-body"/>`)
+      .append($(`<p/>`).text(title))
+      .append($(`<pre/>`)
+        .append($(`<code/>`).text(serverErrorMessage + "\n\nCode: " + serverErrorCode + "\nError id: " + serverErrorId))
+      )
+    );
+  $("#notificationPanel").append(notification);
+  notification.toast({delay: 30000});
+  notification.toast('show');
+}
+
+// ****************************************************************************
+// Application info
+// ****************************************************************************
+
+function applicationInfo() {
+  $.getJSON("info", function (info) {
+       $("#applicationInfo").append("<small>" + info.application + " (version: " + info.version + ", built at: " + info.built + ")</small>");
+   }).fail(function (xhr, ajaxOptions, thrownError) {
+       console.warn("Unable to collect application information");
+   });
+}
+
+// ****************************************************************************
+// TangoColorFactory
+// ****************************************************************************
+
+const SEQUENCE_1 = [0x8AE234, 0xFCE94F, 0x729FCF, 0xE9B96E, 0xAD7FA8];
+const SEQUENCE_2 = [0x73D216, 0xEDD400, 0x3465A4, 0xC17D11, 0x75507B];
+
+var colorMap = new Map;
+var nextColorCount = 0;
+
+function pickColor(object) {
+  let color = colorMap[object];
+  if (color !== undefined) {
+    return color;
+  }
+  color = nextColor();
+  colorMap[object] = color;
+  return color;
+}
+
+function nextColor() {
+  let color;
+  let colorIndex = nextColorCount % SEQUENCE_1.length;
+  let shadeIndex = Math.floor(nextColorCount / SEQUENCE_1.length);
+  if (shadeIndex === 0) {
+    color = SEQUENCE_1[colorIndex];
+  } else if (shadeIndex === 1) {
+    color = SEQUENCE_2[colorIndex];
+  } else {
+    shadeIndex -= 3;
+    let floorColor = SEQUENCE_2[colorIndex];
+    let ceilColor = SEQUENCE_1[colorIndex];
+    let base = Math.floor((shadeIndex / 2) + 1);
+    let divisor = 2;
+    while (base >= divisor) {
+      divisor *= 2;
+    }
+    base = (base * 2) - divisor + 1;
+    let shadePercentage = base / divisor;
+    color = buildPercentageColor(floorColor, ceilColor, shadePercentage);
+  }
+  nextColorCount++;
+  return "#" + color.toString(16);
+}
+
+function buildPercentageColor(floorColor, ceilColor, shadePercentage) {
+  let red = (floorColor & 0xFF0000) + Math.floor(shadePercentage * ((ceilColor & 0xFF0000) - (floorColor & 0xFF0000))) & 0xFF0000;
+  let green = (floorColor & 0x00FF00) + Math.floor(shadePercentage * ((ceilColor & 0x00FF00) - (floorColor & 0x00FF00))) & 0x00FF00;
+  let blue = (floorColor & 0x0000FF) + Math.floor(shadePercentage * ((ceilColor & 0x0000FF) - (floorColor & 0x0000FF))) & 0x0000FF;
+  return red | green | blue;
+}

tests/test_constraints.py

@@ -1,11 +1,29 @@
+"""
+Constraint tests for the employee scheduling quickstart.
+
+Each constraint is tested with both penalizing and non-penalizing scenarios.
+"""
 from solverforge_legacy.solver.test import ConstraintVerifier
 
-from employee_scheduling.domain import *
-from employee_scheduling.constraints import *
+from employee_scheduling.domain import Employee, Shift, EmployeeSchedule
+from employee_scheduling.constraints import (
+    define_constraints,
+    required_skill,
+    no_overlapping_shifts,
+    at_least_10_hours_between_two_shifts,
+    one_shift_per_day,
+    unavailable_employee,
+    undesired_day_for_employee,
+    desired_day_for_employee,
+    balance_employee_shift_assignments,
+)
 
 from datetime import date, datetime, time, timedelta
+import pytest
 
+# Test constants
 DAY_1 = date(2021, 2, 1)
+DAY_2 = date(2021, 2, 2)
 DAY_3 = date(2021, 2, 3)
 DAY_START_TIME = datetime.combine(DAY_1, time(9, 0))
 DAY_END_TIME = datetime.combine(DAY_1, time(17, 0))
@@ -17,708 +35,603 @@ constraint_verifier = ConstraintVerifier.build(
 )
 
 
-def test_required_skill():
-    employee = Employee(name="Amy")
-    (
-        constraint_verifier.verify_that(required_skill)
-        .given(
-            employee,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee,
-            ),
-        )
-        .penalizes(1)
-    )
-
-    employee = Employee(name="Beth", skills={"Skill"})
-    (
-        constraint_verifier.verify_that(required_skill)
-        .given(
-            employee,
-            Shift(
-                id="2",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee,
-            ),
-        )
-        .penalizes(0)
-    )
-
-
-def test_overlapping_shifts():
-    employee1 = Employee(name="Amy")
-    employee2 = Employee(name="Beth")
-    (
-        constraint_verifier.verify_that(no_overlapping_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(timedelta(hours=8) // timedelta(minutes=1))
-    )
-
-    (
-        constraint_verifier.verify_that(no_overlapping_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee2,
-            ),
-        )
-        .penalizes(0)
-    )
-
-    (
-        constraint_verifier.verify_that(no_overlapping_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=AFTERNOON_START_TIME,
-                end=AFTERNOON_END_TIME,
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(timedelta(hours=4) // timedelta(minutes=1))
-    )
-
-
-def test_one_shift_per_day():
-    employee1 = Employee(name="Amy")
-    employee2 = Employee(name="Beth")
-    (
-        constraint_verifier.verify_that(no_overlapping_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes(1)
-    )
-
-    (
-        constraint_verifier.verify_that(no_overlapping_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee2,
-            ),
-        )
-        .penalizes(0)
-    )
-
-    (
-        constraint_verifier.verify_that(no_overlapping_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=AFTERNOON_START_TIME,
-                end=AFTERNOON_END_TIME,
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes(1)
-    )
-
-    (
-        constraint_verifier.verify_that(no_overlapping_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_START_TIME + timedelta(days=1),
-                end=DAY_END_TIME + timedelta(days=1),
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes(0)
-    )
-
-
-def test_at_least_10_hours_between_shifts():
-    employee1 = Employee(name="Amy")
-    employee2 = Employee(name="Beth")
-
-    (
-        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=AFTERNOON_END_TIME,
-                end=DAY_START_TIME + timedelta(days=1),
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(360)
-    )
-
-    (
-        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_END_TIME,
-                end=DAY_START_TIME + timedelta(days=1),
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(600)
-    )
-
-    (
-        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_END_TIME,
-                end=DAY_START_TIME + timedelta(days=1),
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(600)
-    )
-
-    (
-        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_END_TIME + timedelta(hours=10),
-                end=DAY_START_TIME + timedelta(days=1),
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes(0)
-    )
-
-    (
-        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=AFTERNOON_END_TIME,
-                end=DAY_START_TIME + timedelta(days=1),
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee2,
-            ),
-        )
-        .penalizes(0)
-    )
-
-    (
-        constraint_verifier.verify_that(no_overlapping_shifts)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_START_TIME + timedelta(days=1),
-                end=DAY_END_TIME + timedelta(days=1),
-                location="Location 2",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes(0)
-    )
-
-
-def test_unavailable_employee():
-    employee1 = Employee(name="Amy", unavailable_dates={DAY_1, DAY_3})
-    employee2 = Employee(name="Beth")
-
-    (
-        constraint_verifier.verify_that(unavailable_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(timedelta(hours=8) // timedelta(minutes=1))
-    )
-
-    (
-        constraint_verifier.verify_that(unavailable_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME - timedelta(days=1),
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(timedelta(hours=17) // timedelta(minutes=1))
-    )
-
-    (
-        constraint_verifier.verify_that(unavailable_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME + timedelta(days=1),
-                end=DAY_END_TIME + timedelta(days=1),
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes(0)
-    )
-
-    (
-        constraint_verifier.verify_that(unavailable_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee2,
-            ),
-        )
-        .penalizes(0)
-    )
-
-
-def test_undesired_day_for_employee():
-    employee1 = Employee(name="Amy", undesired_dates={DAY_1, DAY_3})
-    employee2 = Employee(name="Beth")
-
-    (
-        constraint_verifier.verify_that(undesired_day_for_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(timedelta(hours=8) // timedelta(minutes=1))
-    )
-
-    (
-        constraint_verifier.verify_that(undesired_day_for_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME - timedelta(days=1),
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by(timedelta(hours=17) // timedelta(minutes=1))
-    )
-
-    (
-        constraint_verifier.verify_that(undesired_day_for_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME + timedelta(days=1),
-                end=DAY_END_TIME + timedelta(days=1),
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes(0)
-    )
-
-    (
-        constraint_verifier.verify_that(undesired_day_for_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee2,
-            ),
-        )
-        .penalizes(0)
-    )
-
-
-def test_desired_day_for_employee():
-    employee1 = Employee(name="Amy", desired_dates={DAY_1, DAY_3})
-    employee2 = Employee(name="Beth")
-
-    (
-        constraint_verifier.verify_that(desired_day_for_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .rewards_with(timedelta(hours=8) // timedelta(minutes=1))
-    )
-
-    (
-        constraint_verifier.verify_that(desired_day_for_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME - timedelta(days=1),
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .rewards_with(timedelta(hours=17) // timedelta(minutes=1))
-    )
-
-    (
-        constraint_verifier.verify_that(desired_day_for_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME + timedelta(days=1),
-                end=DAY_END_TIME + timedelta(days=1),
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .rewards(0)
-    )
-
-    (
-        constraint_verifier.verify_that(desired_day_for_employee)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee2,
-            ),
-        )
-        .rewards(0)
-    )
-
-
-def test_max_shifts_per_employee():
-    employee = Employee(name="Amy")
-
-    # 12 shifts: no violation (at the limit)
-    shifts_12 = [
-        Shift(
-            id=str(i),
-            start=DAY_START_TIME + timedelta(days=i),
-            end=DAY_END_TIME + timedelta(days=i),
+# ========================================
+# Required Skill Tests
+# ========================================
+
+class TestRequiredSkill:
+    """Tests for the required_skill constraint."""
+
+    def test_penalized_when_employee_lacks_skill(self):
+        """Employee without required skill should be penalized."""
+        employee = Employee(name="Amy")  # No skills
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Driving",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(required_skill).given(
+            employee, shift
+        ).penalizes(1)
+
+    def test_not_penalized_when_employee_has_skill(self):
+        """Employee with required skill should not be penalized."""
+        employee = Employee(name="Amy", skills={"Driving"})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Driving",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(required_skill).given(
+            employee, shift
+        ).penalizes(0)
+
+    def test_not_penalized_when_employee_has_multiple_skills(self):
+        """Employee with multiple skills including required should not be penalized."""
+        employee = Employee(name="Amy", skills={"Driving", "First Aid", "Cooking"})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="First Aid",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(required_skill).given(
+            employee, shift
+        ).penalizes(0)
+
+    def test_penalized_when_employee_has_different_skills(self):
+        """Employee with skills but not the required one should be penalized."""
+        employee = Employee(name="Amy", skills={"Cooking", "Cleaning"})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Driving",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(required_skill).given(
+            employee, shift
+        ).penalizes(1)
+
+
+# ========================================
+# Overlapping Shifts Tests
+# ========================================
+
+class TestNoOverlappingShifts:
+    """Tests for the no_overlapping_shifts constraint."""
+
+    def test_penalized_when_shifts_fully_overlap(self):
+        """Same employee with fully overlapping shifts should be penalized."""
+        employee = Employee(name="Amy")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location A",
+            required_skill="Skill",
+            employee=employee,
+        )
+        shift2 = Shift(
+            id="2",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location B",
+            required_skill="Skill",
+            employee=employee,
+        )
+        # 8 hours overlap = 480 minutes
+        constraint_verifier.verify_that(no_overlapping_shifts).given(
+            employee, shift1, shift2
+        ).penalizes_by(480)
+
+    def test_penalized_when_shifts_partially_overlap(self):
+        """Same employee with partially overlapping shifts should be penalized by overlap duration."""
+        employee = Employee(name="Amy")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,  # 9:00
+            end=DAY_END_TIME,      # 17:00
+            location="Location A",
+            required_skill="Skill",
+            employee=employee,
+        )
+        shift2 = Shift(
+            id="2",
+            start=AFTERNOON_START_TIME,  # 13:00
+            end=AFTERNOON_END_TIME,      # 21:00
+            location="Location B",
+            required_skill="Skill",
+            employee=employee,
+        )
+        # Overlap from 13:00 to 17:00 = 4 hours = 240 minutes
+        constraint_verifier.verify_that(no_overlapping_shifts).given(
+            employee, shift1, shift2
+        ).penalizes_by(240)
+
+    def test_not_penalized_when_different_employees(self):
+        """Different employees with overlapping shifts should not be penalized."""
+        employee1 = Employee(name="Amy")
+        employee2 = Employee(name="Beth")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location A",
+            required_skill="Skill",
+            employee=employee1,
+        )
+        shift2 = Shift(
+            id="2",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location B",
+            required_skill="Skill",
+            employee=employee2,
+        )
+        constraint_verifier.verify_that(no_overlapping_shifts).given(
+            employee1, employee2, shift1, shift2
+        ).penalizes(0)
+
+    def test_not_penalized_when_shifts_dont_overlap(self):
+        """Same employee with non-overlapping shifts should not be penalized."""
+        employee = Employee(name="Amy")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location A",
+            required_skill="Skill",
+            employee=employee,
+        )
+        shift2 = Shift(
+            id="2",
+            start=DAY_START_TIME + timedelta(days=1),
+            end=DAY_END_TIME + timedelta(days=1),
+            location="Location B",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(no_overlapping_shifts).given(
+            employee, shift1, shift2
+        ).penalizes(0)
+
+
+# ========================================
+# One Shift Per Day Tests
+# ========================================
+
+class TestOneShiftPerDay:
+    """Tests for the one_shift_per_day constraint."""
+
+    def test_penalized_when_two_shifts_same_day(self):
+        """Employee with two shifts on same day should be penalized."""
+        employee = Employee(name="Amy")
+        shift1 = Shift(
+            id="1",
+            start=datetime.combine(DAY_1, time(6, 0)),
+            end=datetime.combine(DAY_1, time(10, 0)),
+            location="Location A",
+            required_skill="Skill",
+            employee=employee,
+        )
+        shift2 = Shift(
+            id="2",
+            start=datetime.combine(DAY_1, time(18, 0)),
+            end=datetime.combine(DAY_1, time(22, 0)),
+            location="Location B",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(one_shift_per_day).given(
+            employee, shift1, shift2
+        ).penalizes(1)
+
+    def test_not_penalized_when_shifts_different_days(self):
+        """Employee with shifts on different days should not be penalized."""
+        employee = Employee(name="Amy")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location A",
+            required_skill="Skill",
+            employee=employee,
+        )
+        shift2 = Shift(
+            id="2",
+            start=DAY_START_TIME + timedelta(days=1),
+            end=DAY_END_TIME + timedelta(days=1),
+            location="Location B",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(one_shift_per_day).given(
+            employee, shift1, shift2
+        ).penalizes(0)
+
+    def test_not_penalized_when_different_employees_same_day(self):
+        """Different employees with shifts on same day should not be penalized."""
+        employee1 = Employee(name="Amy")
+        employee2 = Employee(name="Beth")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location A",
+            required_skill="Skill",
+            employee=employee1,
+        )
+        shift2 = Shift(
+            id="2",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location B",
+            required_skill="Skill",
+            employee=employee2,
+        )
+        constraint_verifier.verify_that(one_shift_per_day).given(
+            employee1, employee2, shift1, shift2
+        ).penalizes(0)
+
+
+# ========================================
+# 10 Hours Between Shifts Tests
+# ========================================
+
+class TestAtLeast10HoursBetweenShifts:
+    """Tests for the at_least_10_hours_between_two_shifts constraint."""
+
+    def test_penalized_when_less_than_10_hours_gap(self):
+        """Employee with less than 10 hours between shifts should be penalized."""
+        employee = Employee(name="Amy")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,   # 9:00
+            end=DAY_END_TIME,       # 17:00
+            location="Location A",
+            required_skill="Skill",
+            employee=employee,
+        )
+        shift2 = Shift(
+            id="2",
+            start=AFTERNOON_END_TIME,  # 21:00 (4 hours after shift1 ends)
+            end=DAY_START_TIME + timedelta(days=1),
+            location="Location B",
+            required_skill="Skill",
+            employee=employee,
+        )
+        # Gap is 4 hours, need 10 hours, so 6 hours short = 360 minutes penalty
+        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts).given(
+            employee, shift1, shift2
+        ).penalizes_by(360)
+
+    def test_penalized_when_no_gap(self):
+        """Back-to-back shifts should be penalized by full 600 minutes."""
+        employee = Employee(name="Amy")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location A",
+            required_skill="Skill",
+            employee=employee,
+        )
+        shift2 = Shift(
+            id="2",
+            start=DAY_END_TIME,  # Starts exactly when shift1 ends
+            end=DAY_START_TIME + timedelta(days=1),
+            location="Location B",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts).given(
+            employee, shift1, shift2
+        ).penalizes_by(600)
+
+    def test_not_penalized_when_exactly_10_hours_gap(self):
+        """Employee with exactly 10 hours between shifts should not be penalized."""
+        employee = Employee(name="Amy")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,  # 17:00
+            location="Location A",
+            required_skill="Skill",
+            employee=employee,
+        )
+        shift2 = Shift(
+            id="2",
+            start=DAY_END_TIME + timedelta(hours=10),  # 03:00 next day
+            end=DAY_START_TIME + timedelta(days=1),
+            location="Location B",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts).given(
+            employee, shift1, shift2
+        ).penalizes(0)
+
+    def test_not_penalized_when_different_employees(self):
+        """Different employees with back-to-back shifts should not be penalized."""
+        employee1 = Employee(name="Amy")
+        employee2 = Employee(name="Beth")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location A",
+            required_skill="Skill",
+            employee=employee1,
+        )
+        shift2 = Shift(
+            id="2",
+            start=AFTERNOON_END_TIME,
+            end=DAY_START_TIME + timedelta(days=1),
+            location="Location B",
+            required_skill="Skill",
+            employee=employee2,
+        )
+        constraint_verifier.verify_that(at_least_10_hours_between_two_shifts).given(
+            employee1, employee2, shift1, shift2
+        ).penalizes(0)
+
+
+# ========================================
+# Unavailable Employee Tests
+# ========================================
+
+class TestUnavailableEmployee:
+    """Tests for the unavailable_employee constraint."""
+
+    def test_penalized_when_shift_on_unavailable_day(self):
+        """Employee scheduled on unavailable day should be penalized by shift duration."""
+        employee = Employee(name="Amy", unavailable_dates={DAY_1})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,  # DAY_1 at 9:00
+            end=DAY_END_TIME,      # DAY_1 at 17:00
             location="Location",
             required_skill="Skill",
             employee=employee,
         )
-        for i in range(12)
-    ]
-    (
-        constraint_verifier.verify_that(max_shifts_per_employee)
-        .given(employee, *shifts_12)
-        .penalizes(0)
-    )
-
-    # 13 shifts: penalty of 1 (13 - 12 = 1)
-    shifts_13 = [
-        Shift(
-            id=str(i),
-            start=DAY_START_TIME + timedelta(days=i),
-            end=DAY_END_TIME + timedelta(days=i),
+        # 8 hours = 480 minutes
+        constraint_verifier.verify_that(unavailable_employee).given(
+            employee, shift
+        ).penalizes_by(480)
+
+    def test_penalized_proportionally_for_multi_day_shift(self):
+        """Multi-day shift crossing unavailable day should be penalized proportionally."""
+        employee = Employee(name="Amy", unavailable_dates={DAY_1})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME - timedelta(days=1),  # Starts day before
+            end=DAY_END_TIME,                          # Ends on DAY_1
             location="Location",
             required_skill="Skill",
             employee=employee,
         )
-        for i in range(13)
-    ]
-    (
-        constraint_verifier.verify_that(max_shifts_per_employee)
-        .given(employee, *shifts_13)
-        .penalizes_by(1)
-    )
-
-    # 15 shifts: penalty of 3 (15 - 12 = 3)
-    shifts_15 = [
-        Shift(
-            id=str(i),
-            start=DAY_START_TIME + timedelta(days=i),
-            end=DAY_END_TIME + timedelta(days=i),
+        # Overlap with DAY_1 is from midnight to 17:00 = 17 hours = 1020 minutes
+        constraint_verifier.verify_that(unavailable_employee).given(
+            employee, shift
+        ).penalizes_by(1020)
+
+    def test_not_penalized_when_shift_on_different_day(self):
+        """Employee scheduled on available day should not be penalized."""
+        employee = Employee(name="Amy", unavailable_dates={DAY_1})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME + timedelta(days=1),  # DAY_2
+            end=DAY_END_TIME + timedelta(days=1),
             location="Location",
             required_skill="Skill",
             employee=employee,
         )
-        for i in range(15)
-    ]
-    (
-        constraint_verifier.verify_that(max_shifts_per_employee)
-        .given(employee, *shifts_15)
-        .penalizes_by(3)
-    )
-
-
-def test_balance_employee_shift_assignments():
-    employee1 = Employee(name="Amy", desired_dates={DAY_1, DAY_3})
-    employee2 = Employee(name="Beth")
-
-    # No employees have shifts assigned; the schedule is perfectly balanced.
-    (
-        constraint_verifier.verify_that(balance_employee_shift_assignments)
-        .given(employee1, employee2)
-        .penalizes_by(0)
-    )
-
-    # Only one employee has shifts assigned; the schedule is less balanced.
-    (
-        constraint_verifier.verify_that(balance_employee_shift_assignments)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-        )
-        .penalizes_by_more_than(0)
-    )
-
-    # Every employee has a shift assigned; the schedule is once again perfectly balanced.
-    (
-        constraint_verifier.verify_that(balance_employee_shift_assignments)
-        .given(
-            employee1,
-            employee2,
-            Shift(
-                id="1",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee1,
-            ),
-            Shift(
-                id="2",
-                start=DAY_START_TIME,
-                end=DAY_END_TIME,
-                location="Location",
-                required_skill="Skill",
-                employee=employee2,
-            ),
-        )
-        .penalizes_by(0)
-    )
+        constraint_verifier.verify_that(unavailable_employee).given(
+            employee, shift
+        ).penalizes(0)
+
+    def test_not_penalized_when_different_employee(self):
+        """Different employee (without unavailable dates) should not be penalized."""
+        employee1 = Employee(name="Amy", unavailable_dates={DAY_1})
+        employee2 = Employee(name="Beth")  # No unavailable dates
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee2,
+        )
+        constraint_verifier.verify_that(unavailable_employee).given(
+            employee1, employee2, shift
+        ).penalizes(0)
+
+    def test_penalized_for_multiple_unavailable_days(self):
+        """Shift crossing multiple unavailable days should be penalized for both."""
+        employee = Employee(name="Amy", unavailable_dates={DAY_1, DAY_3})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee,
+        )
+        # Only DAY_1 overlaps (DAY_3 is 2 days later)
+        constraint_verifier.verify_that(unavailable_employee).given(
+            employee, shift
+        ).penalizes_by(480)
+
+
+# ========================================
+# Undesired Day Tests
+# ========================================
+
+class TestUndesiredDayForEmployee:
+    """Tests for the undesired_day_for_employee constraint (soft)."""
+
+    def test_penalized_when_shift_on_undesired_day(self):
+        """Employee scheduled on undesired day should be penalized."""
+        employee = Employee(name="Amy", undesired_dates={DAY_1})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(undesired_day_for_employee).given(
+            employee, shift
+        ).penalizes_by(480)
+
+    def test_not_penalized_when_shift_on_different_day(self):
+        """Employee scheduled on non-undesired day should not be penalized."""
+        employee = Employee(name="Amy", undesired_dates={DAY_1})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME + timedelta(days=1),
+            end=DAY_END_TIME + timedelta(days=1),
+            location="Location",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(undesired_day_for_employee).given(
+            employee, shift
+        ).penalizes(0)
+
+    def test_not_penalized_when_different_employee(self):
+        """Different employee without undesired dates should not be penalized."""
+        employee1 = Employee(name="Amy", undesired_dates={DAY_1})
+        employee2 = Employee(name="Beth")
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee2,
+        )
+        constraint_verifier.verify_that(undesired_day_for_employee).given(
+            employee1, employee2, shift
+        ).penalizes(0)
+
+
+# ========================================
+# Desired Day Tests
+# ========================================
+
+class TestDesiredDayForEmployee:
+    """Tests for the desired_day_for_employee constraint (soft reward)."""
+
+    def test_rewarded_when_shift_on_desired_day(self):
+        """Employee scheduled on desired day should be rewarded."""
+        employee = Employee(name="Amy", desired_dates={DAY_1})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(desired_day_for_employee).given(
+            employee, shift
+        ).rewards_with(480)
+
+    def test_not_rewarded_when_shift_on_different_day(self):
+        """Employee scheduled on non-desired day should not be rewarded."""
+        employee = Employee(name="Amy", desired_dates={DAY_1})
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME + timedelta(days=1),
+            end=DAY_END_TIME + timedelta(days=1),
+            location="Location",
+            required_skill="Skill",
+            employee=employee,
+        )
+        constraint_verifier.verify_that(desired_day_for_employee).given(
+            employee, shift
+        ).rewards(0)
+
+    def test_not_rewarded_when_different_employee(self):
+        """Different employee without desired dates should not be rewarded."""
+        employee1 = Employee(name="Amy", desired_dates={DAY_1})
+        employee2 = Employee(name="Beth")
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee2,
+        )
+        constraint_verifier.verify_that(desired_day_for_employee).given(
+            employee1, employee2, shift
+        ).rewards(0)
+
+
+# ========================================
+# Balance Employee Shift Assignments Tests
+# ========================================
+
+class TestBalanceEmployeeShiftAssignments:
+    """Tests for the balance_employee_shift_assignments constraint."""
+
+    def test_no_penalty_when_no_shifts(self):
+        """No shifts assigned should have zero imbalance."""
+        employee1 = Employee(name="Amy")
+        employee2 = Employee(name="Beth")
+        constraint_verifier.verify_that(balance_employee_shift_assignments).given(
+            employee1, employee2
+        ).penalizes_by(0)
+
+    def test_penalized_when_unbalanced(self):
+        """Only one employee with shifts should be penalized (imbalanced)."""
+        employee1 = Employee(name="Amy")
+        employee2 = Employee(name="Beth")
+        shift = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee1,
+        )
+        constraint_verifier.verify_that(balance_employee_shift_assignments).given(
+            employee1, employee2, shift
+        ).penalizes_by_more_than(0)
+
+    def test_no_penalty_when_balanced(self):
+        """Equal shifts per employee should have zero imbalance."""
+        employee1 = Employee(name="Amy")
+        employee2 = Employee(name="Beth")
+        shift1 = Shift(
+            id="1",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee1,
+        )
+        shift2 = Shift(
+            id="2",
+            start=DAY_START_TIME,
+            end=DAY_END_TIME,
+            location="Location",
+            required_skill="Skill",
+            employee=employee2,
+        )
+        constraint_verifier.verify_that(balance_employee_shift_assignments).given(
+            employee1, employee2, shift1, shift2
+        ).penalizes_by(0)

tests/test_feasible.py

@@ -1,12 +1,9 @@
-from solverforge_legacy.solver import SolverFactory
-from solverforge_legacy.solver.config import (
-    SolverConfig,
-    ScoreDirectorFactoryConfig,
-    TerminationConfig,
-    Duration,
-    TerminationCompositionStyle,
-)
+"""
+Integration tests for the employee scheduling solver.
 
+Tests that the solver can find feasible solutions for demo data
+and that the REST API works correctly.
+"""
 from employee_scheduling.rest_api import app
 from employee_scheduling.domain import EmployeeScheduleModel
 from employee_scheduling.converters import model_to_schedule
@@ -14,11 +11,14 @@ from employee_scheduling.converters import model_to_schedule
 from fastapi.testclient import TestClient
 from time import sleep
 from pytest import fail
+import pytest
 
 client = TestClient(app)
 
 
+@pytest.mark.timeout(120)
 def test_feasible():
+    """Test that the solver can find a feasible solution for SMALL demo data."""
     demo_data_response = client.get("/demo-data/SMALL")
     assert demo_data_response.status_code == 200
 
@@ -27,16 +27,138 @@ def test_feasible():
     job_id = job_id_response.text[1:-1]
 
     ATTEMPTS = 1_000
+    best_score = None
     for _ in range(ATTEMPTS):
         sleep(0.1)
         schedule_response = client.get(f"/schedules/{job_id}")
         schedule_json = schedule_response.json()
         schedule_model = EmployeeScheduleModel.model_validate(schedule_json)
         schedule = model_to_schedule(schedule_model)
-        if schedule.score is not None and schedule.score.is_feasible:
-            stop_solving_response = client.delete(f"/schedules/{job_id}")
-            assert stop_solving_response.status_code == 200
-            return
+        if schedule.score is not None:
+            best_score = schedule.score
+            if schedule.score.is_feasible:
+                stop_solving_response = client.delete(f"/schedules/{job_id}")
+                assert stop_solving_response.status_code == 200
+                return
 
     client.delete(f"/schedules/{job_id}")
-    fail("solution is not feasible")
+    fail(f"Solution is not feasible after 100 seconds. Best score: {best_score}")
+
+
+def test_demo_data_list():
+    """Test that demo data list endpoint returns available datasets."""
+    response = client.get("/demo-data")
+    assert response.status_code == 200
+    data = response.json()
+    assert isinstance(data, list)
+    assert len(data) > 0
+    assert "SMALL" in data
+
+
+def test_demo_data_small_structure():
+    """Test that SMALL demo data has expected structure."""
+    response = client.get("/demo-data/SMALL")
+    assert response.status_code == 200
+    data = response.json()
+
+    # Check required fields
+    assert "employees" in data
+    assert "shifts" in data
+
+    # Validate employees
+    assert len(data["employees"]) > 0
+    for employee in data["employees"]:
+        assert "name" in employee
+
+    # Validate shifts
+    assert len(data["shifts"]) > 0
+    for shift in data["shifts"]:
+        assert "id" in shift
+        assert "start" in shift
+        assert "end" in shift
+        assert "location" in shift
+        assert "requiredSkill" in shift
+
+
+def test_solver_start_and_stop():
+    """Test that solver can be started and stopped."""
+    demo_data_response = client.get("/demo-data/SMALL")
+    assert demo_data_response.status_code == 200
+
+    # Start solving
+    start_response = client.post("/schedules", json=demo_data_response.json())
+    assert start_response.status_code == 200
+    job_id = start_response.text[1:-1]
+
+    # Wait a bit
+    sleep(0.5)
+
+    # Check status
+    status_response = client.get(f"/schedules/{job_id}")
+    assert status_response.status_code == 200
+    schedule = status_response.json()
+    assert "solverStatus" in schedule
+
+    # Stop solving
+    stop_response = client.delete(f"/schedules/{job_id}")
+    assert stop_response.status_code == 200
+
+
+def test_solver_assigns_employees():
+    """Test that solver actually assigns employees to shifts."""
+    demo_data_response = client.get("/demo-data/SMALL")
+    assert demo_data_response.status_code == 200
+
+    job_id_response = client.post("/schedules", json=demo_data_response.json())
+    assert job_id_response.status_code == 200
+    job_id = job_id_response.text[1:-1]
+
+    # Wait for some solving
+    sleep(2)
+
+    schedule_response = client.get(f"/schedules/{job_id}")
+    schedule_json = schedule_response.json()
+
+    # Check that some shifts have employees assigned
+    assigned_shifts = [s for s in schedule_json["shifts"] if s.get("employee") is not None]
+    assert len(assigned_shifts) > 0, "Solver should assign some employees to shifts"
+
+    client.delete(f"/schedules/{job_id}")
+
+
+def test_score_analysis():
+    """Test that score analysis endpoint returns constraint analysis."""
+    demo_data_response = client.get("/demo-data/SMALL")
+    assert demo_data_response.status_code == 200
+
+    # Start solving and get a scored solution
+    job_id_response = client.post("/schedules", json=demo_data_response.json())
+    assert job_id_response.status_code == 200
+    job_id = job_id_response.text[1:-1]
+
+    # Wait for solver to produce a score
+    sleep(2)
+
+    schedule_response = client.get(f"/schedules/{job_id}")
+    schedule_json = schedule_response.json()
+
+    # Stop solving
+    client.delete(f"/schedules/{job_id}")
+
+    # Call analyze endpoint
+    analyze_response = client.put("/schedules/analyze", json=schedule_json)
+    assert analyze_response.status_code == 200
+    analysis = analyze_response.json()
+
+    # Verify structure
+    assert "constraints" in analysis
+    assert isinstance(analysis["constraints"], list)
+    assert len(analysis["constraints"]) > 0
+
+    # Check constraint structure
+    for constraint in analysis["constraints"]:
+        assert "name" in constraint
+        assert "weight" in constraint
+        assert "score" in constraint
+        assert "matches" in constraint
+        assert isinstance(constraint["matches"], list)