@fleetbase/fleetops-engine 0.6.71 → 0.6.72

package/server/tests/Unit/Jobs/FinalizeApiOrderCreationDispatchGuardTest.php

@@ -0,0 +1,266 @@
+<?php
+
+if (!function_exists('Fleetbase\FleetOps\Models\dispatch')) {
+    eval('namespace Fleetbase\FleetOps\Models; function dispatch($job) { return \FleetOpsOrderUnitDispatchRecorder::record($job); }');
+}
+
+if (!function_exists('Fleetbase\FleetOps\Models\event')) {
+    eval('namespace Fleetbase\FleetOps\Models; function event($event = null) { \FleetOpsOrderUnitDispatchRecorder::$events[] = $event; return $event; }');
+}
+
+if (!function_exists('Fleetbase\FleetOps\Models\now')) {
+    eval('namespace Fleetbase\FleetOps\Models; function now($tz = null) { return \Illuminate\Support\Carbon::now($tz); }');
+}
+
+if (!class_exists('Fleetbase\FleetOps\Events\OrderDispatched', false)) {
+    eval('namespace Fleetbase\FleetOps\Events; class OrderDispatched { public function __construct(public $order) {} }');
+}
+
+if (!class_exists('FleetOpsOrderUnitDispatchRecorder', false)) {
+    class FleetOpsOrderUnitDispatchRecorder
+    {
+        public static array $jobs   = [];
+        public static array $events = [];
+
+        public static function reset(): void
+        {
+            static::$jobs   = [];
+            static::$events = [];
+        }
+
+        public static function record($job): object
+        {
+            static::$jobs[] = $job;
+
+            if ($job instanceof Closure) {
+                $job();
+            }
+
+            return new class {
+                public function afterCommit(): self
+                {
+                    return $this;
+                }
+            };
+        }
+    }
+}
+
+use Fleetbase\FleetOps\Events\OrderDispatched;
+use Fleetbase\FleetOps\Flow\Activity;
+use Fleetbase\FleetOps\Jobs\FinalizeApiOrderCreation;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\OrderConfig;
+use Fleetbase\FleetOps\Models\ServiceQuote;
+use Fleetbase\FleetOps\Models\TrackingStatus;
+use Illuminate\Support\Carbon;
+
+class FleetOpsQueuedDispatchOrderFake extends Order
+{
+    public bool $quietSaved         = false;
+    public array $calls             = [];
+    public array $activityRows      = [];
+    public array $statuses          = [];
+    public ?OrderConfig $fakeConfig = null;
+
+    public function getDateFormat()
+    {
+        return 'Y-m-d H:i:s';
+    }
+
+    public function load($relations)
+    {
+        return $this;
+    }
+
+    public function saveQuietly(array $options = []): bool
+    {
+        $this->quietSaved = true;
+
+        return true;
+    }
+
+    public function flushAttributesCache(): bool
+    {
+        return true;
+    }
+
+    public function config(): ?OrderConfig
+    {
+        return $this->fakeConfig;
+    }
+
+    public function notifyDriverAssigned(): void
+    {
+        $this->calls[] = 'notifyDriverAssigned';
+    }
+
+    public function setPreliminaryDistanceAndTime(): void
+    {
+        $this->calls[] = 'setPreliminaryDistanceAndTime';
+    }
+
+    public function purchaseServiceQuote($serviceQuote, $meta = [])
+    {
+        $this->calls[] = 'purchaseServiceQuote';
+    }
+
+    public function insertActivity(Activity $activity, $location = [], $proof = null): string
+    {
+        $this->activityRows[] = $activity->code;
+
+        return 'tracking_status_public';
+    }
+
+    public function setStatus(?string $status, $andSave = true)
+    {
+        $this->statuses[] = $status;
+        $this->status     = $status;
+
+        return $this;
+    }
+}
+
+class FleetOpsQueuedDispatchConfigFake extends OrderConfig
+{
+    public function getDispatchActivity(): ?Activity
+    {
+        return new Activity(['code' => 'dispatched']);
+    }
+}
+
+class FleetOpsQueuedDispatchJobProbe extends FinalizeApiOrderCreation
+{
+    public ?Order $order = null;
+    public array $ready  = [];
+
+    protected function findOrder(): ?Order
+    {
+        return $this->order;
+    }
+
+    protected function findServiceQuote(): ?ServiceQuote
+    {
+        return null;
+    }
+
+    protected function fireOrderReady(Order $order): void
+    {
+        $this->ready[] = $order->uuid;
+    }
+}
+
+function fleetopsQueuedDispatchTrackingStatus(string $code): TrackingStatus
+{
+    $status       = new TrackingStatus();
+    $status->code = $code;
+
+    return $status;
+}
+
+function fleetopsQueuedDispatchOrder(array $attributes = [], array $trackingCodes = ['CREATED'], array $lifecycle = []): FleetOpsQueuedDispatchOrderFake
+{
+    $config = new FleetOpsQueuedDispatchConfigFake();
+    $config->setRawAttributes(['meta' => json_encode($lifecycle ? ['lifecycle' => $lifecycle] : [])], true);
+
+    $order = new FleetOpsQueuedDispatchOrderFake();
+    $order->setRawAttributes(array_merge([
+        'uuid'                 => 'order-uuid',
+        'tracking_number_uuid' => 'tracking-number-uuid',
+        'status'               => 'created',
+        'dispatched'           => false,
+        'started'              => false,
+    ], $attributes), true);
+    $order->fakeConfig = $config;
+    $order->setRelation('trackingStatuses', collect(array_map('fleetopsQueuedDispatchTrackingStatus', $trackingCodes)));
+    $order->setRelation('driverAssigned', null);
+    $order->setRelation('payload', null);
+
+    return $order;
+}
+
+function fleetopsRunQueuedDispatch(Order $order): FleetOpsQueuedDispatchJobProbe
+{
+    $job        = new FleetOpsQueuedDispatchJobProbe($order->uuid, null, true);
+    $job->order = $order;
+    $job->handle();
+
+    return $job;
+}
+
+beforeEach(function () {
+    FleetOpsOrderUnitDispatchRecorder::reset();
+    Carbon::setTestNow(Carbon::parse('2026-10-11 09:30:00'));
+});
+
+afterEach(function () {
+    Carbon::setTestNow();
+});
+
+test('queued api dispatch still dispatches an order that is waiting at created', function () {
+    $order = fleetopsQueuedDispatchOrder();
+
+    $job = fleetopsRunQueuedDispatch($order);
+
+    expect($order->dispatched)->toBeTrue()
+        ->and($order->dispatched_at->toDateTimeString())->toBe('2026-10-11 09:30:00')
+        ->and($order->status)->toBe('dispatched')
+        ->and($order->activityRows)->toBe(['dispatched'])
+        ->and(FleetOpsOrderUnitDispatchRecorder::$events)->toHaveCount(1)
+        ->and(FleetOpsOrderUnitDispatchRecorder::$events[0])->toBeInstanceOf(OrderDispatched::class)
+        ->and($job->ready)->toBe(['order-uuid']);
+});
+
+test('queued api dispatch is a no-op once the order was dispatched and started', function () {
+    $dispatchedAt = Carbon::parse('2026-10-11 09:00:00');
+    $startedAt    = Carbon::parse('2026-10-11 09:10:00');
+    $order        = fleetopsQueuedDispatchOrder([
+        'status'        => 'started',
+        'dispatched'    => true,
+        'dispatched_at' => $dispatchedAt->toDateTimeString(),
+        'started'       => true,
+        'started_at'    => $startedAt->toDateTimeString(),
+    ], ['CREATED', 'DISPATCHED', 'STARTED']);
+
+    $job = fleetopsRunQueuedDispatch($order);
+
+    expect($order->status)->toBe('started')
+        ->and($order->dispatched_at->toDateTimeString())->toBe('2026-10-11 09:00:00')
+        ->and($order->started_at->toDateTimeString())->toBe('2026-10-11 09:10:00')
+        ->and($order->quietSaved)->toBeFalse()
+        ->and($order->activityRows)->toBe([])
+        ->and($order->statuses)->toBe([])
+        ->and(FleetOpsOrderUnitDispatchRecorder::$jobs)->toBe([])
+        ->and(FleetOpsOrderUnitDispatchRecorder::$events)->toBe([])
+        ->and($order->calls)->toBe(['notifyDriverAssigned', 'setPreliminaryDistanceAndTime', 'purchaseServiceQuote'])
+        ->and($job->ready)->toBe(['order-uuid']);
+});
+
+test('an order is only awaiting dispatch at its initial status with nothing recorded', function () {
+    expect(fleetopsQueuedDispatchOrder()->isAwaitingDispatch())->toBeTrue()
+        ->and(fleetopsQueuedDispatchOrder(['status' => null])->isAwaitingDispatch())->toBeTrue()
+        ->and(fleetopsQueuedDispatchOrder(['status' => 'pending'], ['PENDING'], ['initial' => 'pending'])->isAwaitingDispatch())->toBeTrue()
+        ->and(fleetopsQueuedDispatchOrder(['dispatched' => true])->isAwaitingDispatch())->toBeFalse()
+        ->and(fleetopsQueuedDispatchOrder(['dispatched_at' => '2026-10-11 09:00:00'])->isAwaitingDispatch())->toBeFalse()
+        ->and(fleetopsQueuedDispatchOrder(['started' => true])->isAwaitingDispatch())->toBeFalse()
+        ->and(fleetopsQueuedDispatchOrder(['started_at' => '2026-10-11 09:10:00'])->isAwaitingDispatch())->toBeFalse()
+        ->and(fleetopsQueuedDispatchOrder(['status' => 'enroute'])->isAwaitingDispatch())->toBeFalse()
+        ->and(fleetopsQueuedDispatchOrder(['status' => 'completed'])->isAwaitingDispatch())->toBeFalse()
+        ->and(fleetopsQueuedDispatchOrder([], ['CREATED', 'DISPATCHED'])->isAwaitingDispatch())->toBeFalse();
+
+    $withoutConfig             = fleetopsQueuedDispatchOrder(['status' => 'pending']);
+    $withoutConfig->fakeConfig = null;
+
+    expect($withoutConfig->isAwaitingDispatch())->toBeFalse();
+});
+
+test('a terminal or later status on a custom lifecycle is never dispatched by the queued job', function () {
+    $order = fleetopsQueuedDispatchOrder(['status' => 'delivered'], ['PENDING', 'DELIVERED'], ['initial' => 'pending', 'completed' => 'delivered']);
+
+    fleetopsRunQueuedDispatch($order);
+
+    expect($order->status)->toBe('delivered')
+        ->and($order->dispatched)->toBeFalse()
+        ->and($order->activityRows)->toBe([])
+        ->and(FleetOpsOrderUnitDispatchRecorder::$events)->toBe([]);
+});

package/server/tests/Unit/Listeners/HandleGeofenceEnteredTest.php

@@ -14,8 +14,11 @@ use Fleetbase\FleetOps\Listeners\HandleGeofenceEntered;
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\GeofenceEventLog;
 use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\Waypoint;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
 use Illuminate\Database\ConnectionResolver;
 use Illuminate\Database\Eloquent\Model as EloquentModel;
@@ -96,8 +99,12 @@ function fleetopsHandleGeofenceEnteredConnection(): SQLiteConnection
     $connection = new SQLiteConnection($pdo, 'default');
     $connection->statement('create table geofence_events_log (uuid varchar(64) primary key, company_uuid varchar(64), driver_uuid varchar(64) null, vehicle_uuid varchar(64) null, order_uuid varchar(64) null, subject_uuid varchar(64) null, subject_type varchar(255) null, subject_name varchar(255) null, geofence_uuid varchar(64), geofence_type varchar(64), geofence_name varchar(255) null, event_type varchar(64), latitude numeric null, longitude numeric null, speed_kmh numeric null, dwell_duration_minutes integer null, occurred_at datetime null, created_at datetime null, updated_at datetime null)');
 
+    $connection->statement('create table tracking_numbers (id integer primary key autoincrement, uuid varchar(64), public_id varchar(64) null, company_uuid varchar(64) null, status_uuid varchar(64) null, created_at datetime null, updated_at datetime null, deleted_at datetime null)');
+    $connection->statement('create table tracking_statuses (id integer primary key autoincrement, uuid varchar(64), public_id varchar(64) null, company_uuid varchar(64) null, tracking_number_uuid varchar(64) null, code varchar(64) null, complete integer null, created_at datetime null, updated_at datetime null, deleted_at datetime null)');
+
     $resolver = new ConnectionResolver([
         'default' => $connection,
+        'mysql'   => $connection,
     ]);
     $resolver->setDefaultConnection('default');
     EloquentModel::setConnectionResolver($resolver);
@@ -212,7 +219,73 @@ test('geofence entered listener writes vehicle entry logs with current order con
         ->and($log->subject_name)->toBe('Dock Van');
 });
 
+function fleetopsEnteredZone(string $name, float $lat, float $lng): object
+{
+    return new class($name, $lat, $lng) {
+        public string $uuid;
+        public string $public_id;
+
+        public function __construct(public string $name, private float $lat, private float $lng)
+        {
+            $this->uuid      = $name . '-uuid';
+            $this->public_id = $name . '-public';
+        }
+
+        public function getLatitudeAttribute(): float
+        {
+            return $this->lat;
+        }
+
+        public function getLongitudeAttribute(): float
+        {
+            return $this->lng;
+        }
+    };
+}
+
+function fleetopsEnteredPlace(string $uuid, ?Point $location): Place
+{
+    $place = new Place();
+    $place->setRawAttributes(['uuid' => $uuid, 'public_id' => $uuid . '-public', 'location' => $location], true);
+
+    return $place;
+}
+
+/**
+ * Build a pickup -> dropoff payload. The pickup sits on the default event
+ * zone centroid; the dropoff is roughly 9km away.
+ */
+function fleetopsEnteredEndpointPayload(?string $currentWaypointUuid = null, ?string $pickupTrackingNumberUuid = null): Payload
+{
+    $payload = new Payload();
+    $payload->setRawAttributes([
+        'uuid'                        => 'payload-uuid',
+        'current_waypoint_uuid'       => $currentWaypointUuid,
+        'pickup_tracking_number_uuid' => $pickupTrackingNumberUuid,
+    ], true);
+    $payload->setRelation('pickup', fleetopsEnteredPlace('pickup-place', new Point(1.3521, 103.8198)));
+    $payload->setRelation('dropoff', fleetopsEnteredPlace('dropoff-place', new Point(1.3000, 103.9000)));
+    $payload->setRelation('waypoints', collect());
+    $payload->setRelation('waypointMarkers', collect());
+
+    return $payload;
+}
+
+function fleetopsEnteredCompleteStatus(SQLiteConnection $connection, string $trackingNumberUuid): void
+{
+    $connection->table('tracking_numbers')->insert(['uuid' => $trackingNumberUuid, 'status_uuid' => $trackingNumberUuid . '-status']);
+    $connection->table('tracking_statuses')->insert(['uuid' => $trackingNumberUuid . '-status', 'tracking_number_uuid' => $trackingNumberUuid, 'code' => 'completed', 'complete' => 1]);
+}
+
+function fleetopsEnteredArrive(Order $order, object $zone): void
+{
+    $driver = fleetopsEnteredDriver($order);
+
+    (new HandleGeofenceEntered())->handle(fleetopsEnteredEvent($driver, $zone));
+}
+
 test('geofence entered arrival handles destination and status failures', function () {
+    fleetopsHandleGeofenceEnteredConnection();
     $listener = new HandleGeofenceEntered();
     $arrival  = new ReflectionMethod(HandleGeofenceEntered::class, 'handleOrderArrival');
     $arrival->setAccessible(true);
@@ -220,37 +293,124 @@ test('geofence entered arrival handles destination and status failures', functio
     $driver = fleetopsEnteredDriver();
     $event  = fleetopsEnteredEvent($driver);
 
-    $destinationFailure = fleetopsEnteredOrder(new class {
-        public function getPickupOrCurrentWaypoint(): mixed
+    $throwingPayload = new class extends Payload {
+        public function loadMissing($relations)
         {
             throw new RuntimeException('destination failed');
         }
-    });
+    };
+    $destinationFailure = fleetopsEnteredOrder($throwingPayload);
     $arrival->invoke($listener, $driver, $event->geofence, $destinationFailure, $event);
 
-    $placeFailure = fleetopsEnteredOrder(new class {
-        public function getPickupOrCurrentWaypoint(): object
-        {
-            return new class {
-                public function getPlace(): mixed
-                {
-                    throw new RuntimeException('place failed');
-                }
-            };
-        }
-    });
-    $arrival->invoke($listener, $driver, $event->geofence, $placeFailure, $event);
+    $emptyPayload = new Payload();
+    $emptyPayload->setRelation('pickup', null);
+    $emptyPayload->setRelation('dropoff', null);
+    $emptyPayload->setRelation('waypoints', collect());
+    $emptyPayload->setRelation('waypointMarkers', collect());
+    $noStops = fleetopsEnteredOrder($emptyPayload);
+    $arrival->invoke($listener, $driver, $event->geofence, $noStops, $event);
 
-    $statusFailure = fleetopsEnteredOrder(new class {
-        public function getPickupOrCurrentWaypoint(): object
-        {
-            return (object) ['place' => (object) ['location' => new Point(1.3521, 103.8198)]];
-        }
-    });
+    $statusFailure                = fleetopsEnteredOrder(fleetopsEnteredEndpointPayload());
     $statusFailure->throwOnStatus = true;
     $arrival->invoke($listener, $driver, $event->geofence, $statusFailure, $event);
 
     expect($destinationFailure->calls)->toBe([])
-        ->and($placeFailure->calls)->toBe([])
+        ->and($noStops->calls)->toBe([])
         ->and($statusFailure->calls)->toBe([]);
 });
+
+test('geofence entered arrival targets the pickup before the pickup is completed', function () {
+    fleetopsHandleGeofenceEnteredConnection();
+
+    $atDropoff = fleetopsEnteredOrder(fleetopsEnteredEndpointPayload());
+    fleetopsEnteredArrive($atDropoff, fleetopsEnteredZone('dropoff-zone', 1.3000, 103.9000));
+
+    $atPickup = fleetopsEnteredOrder(fleetopsEnteredEndpointPayload('pickup-place'));
+    fleetopsEnteredArrive($atPickup, fleetopsEnteredZone('pickup-zone', 1.3521, 103.8198));
+
+    expect($atDropoff->calls)->toBe([])
+        ->and($atDropoff->status)->toBe('dispatched')
+        ->and($atPickup->calls[0])->toBe(['setStatus', 'arrived', true])
+        ->and($atPickup->calls[1][1]->get('details'))->toBe('Driver entered destination geofence "pickup-zone".');
+});
+
+test('geofence entered arrival targets the dropoff once the order has advanced past the pickup', function () {
+    fleetopsHandleGeofenceEnteredConnection();
+
+    $atPickup = fleetopsEnteredOrder(fleetopsEnteredEndpointPayload('dropoff-place'));
+    fleetopsEnteredArrive($atPickup, fleetopsEnteredZone('pickup-zone', 1.3521, 103.8198));
+
+    $atDropoff = fleetopsEnteredOrder(fleetopsEnteredEndpointPayload('dropoff-place'));
+    fleetopsEnteredArrive($atDropoff, fleetopsEnteredZone('dropoff-zone', 1.3000, 103.9000));
+
+    expect($atPickup->calls)->toBe([])
+        ->and($atDropoff->calls[0])->toBe(['setStatus', 'arrived', true])
+        ->and($atDropoff->calls[1][1]->get('details'))->toBe('Driver entered destination geofence "dropoff-zone".');
+});
+
+test('geofence entered arrival skips a completed pickup the payload pointer has not advanced past', function () {
+    $connection = fleetopsHandleGeofenceEnteredConnection();
+    fleetopsEnteredCompleteStatus($connection, 'pickup-tracking');
+
+    $atPickup = fleetopsEnteredOrder(fleetopsEnteredEndpointPayload('pickup-place', 'pickup-tracking'));
+    fleetopsEnteredArrive($atPickup, fleetopsEnteredZone('pickup-zone', 1.3521, 103.8198));
+
+    $atDropoff = fleetopsEnteredOrder(fleetopsEnteredEndpointPayload(null, 'pickup-tracking'));
+    fleetopsEnteredArrive($atDropoff, fleetopsEnteredZone('dropoff-zone', 1.3000, 103.9000));
+
+    expect($atPickup->calls)->toBe([])
+        ->and($atDropoff->calls[0])->toBe(['setStatus', 'arrived', true]);
+});
+
+test('geofence entered arrival targets the current stop of a multi-waypoint order', function () {
+    $connection = fleetopsHandleGeofenceEnteredConnection();
+    fleetopsEnteredCompleteStatus($connection, 'first-tracking');
+
+    $multiDropPayload = function (?string $currentWaypointUuid): Payload {
+        $payload = new Payload();
+        $payload->setRawAttributes(['uuid' => 'multi-payload-uuid', 'current_waypoint_uuid' => $currentWaypointUuid], true);
+        $payload->setRelation('pickup', null);
+        $payload->setRelation('dropoff', null);
+        $payload->setRelation('waypoints', collect());
+
+        $markers = collect([
+            ['first', 'first-tracking', new Point(1.3521, 103.8198)],
+            ['second', null, new Point(1.3000, 103.9000)],
+            ['third', null, new Point(1.4000, 103.7000)],
+        ])->map(function (array $stop, int $index) {
+            [$name, $trackingNumberUuid, $location] = $stop;
+
+            $waypoint = new Waypoint();
+            $waypoint->setRawAttributes([
+                'uuid'                 => $name . '-waypoint',
+                'place_uuid'           => $name . '-place',
+                'tracking_number_uuid' => $trackingNumberUuid,
+                'order'                => $index,
+            ], true);
+            $waypoint->setRelation('place', fleetopsEnteredPlace($name . '-place', $location));
+            $waypoint->setRelation('trackingNumber', null);
+
+            return $waypoint;
+        });
+        $payload->setRelation('waypointMarkers', $markers);
+
+        return $payload;
+    };
+
+    $atCompletedStop = fleetopsEnteredOrder($multiDropPayload('second-place'));
+    fleetopsEnteredArrive($atCompletedStop, fleetopsEnteredZone('first-zone', 1.3521, 103.8198));
+
+    $atLaterStop = fleetopsEnteredOrder($multiDropPayload('second-place'));
+    fleetopsEnteredArrive($atLaterStop, fleetopsEnteredZone('third-zone', 1.4000, 103.7000));
+
+    $atCurrentStop = fleetopsEnteredOrder($multiDropPayload('second-place'));
+    fleetopsEnteredArrive($atCurrentStop, fleetopsEnteredZone('second-zone', 1.3000, 103.9000));
+
+    $staleFirstStop = fleetopsEnteredOrder($multiDropPayload(null));
+    fleetopsEnteredArrive($staleFirstStop, fleetopsEnteredZone('second-zone', 1.3000, 103.9000));
+
+    expect($atCompletedStop->calls)->toBe([])
+        ->and($atLaterStop->calls)->toBe([])
+        ->and($atCurrentStop->calls[0])->toBe(['setStatus', 'arrived', true])
+        ->and($staleFirstStop->calls[0])->toBe(['setStatus', 'arrived', true]);
+});

package/server/tests/Unit/Listeners/HandleUserRemovedFromCompanyTest.php

@@ -21,6 +21,11 @@ class FleetOpsUserRemovedCompanyDriverQueryFake
 {
     public bool $deleted = false;
 
+    public function get(): Illuminate\Support\Collection
+    {
+        return collect([$this]);
+    }
+
     public function delete(): void
     {
         $this->deleted = true;

package/server/tests/Unit/Models/DriverAssignVehicleTest.php

@@ -0,0 +1,81 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\Tests\Support\TrackingPageDatabase;
+use Illuminate\Cache\ArrayStore;
+use Illuminate\Cache\Repository;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Facades\Cache;
+
+beforeEach(function () {
+    Cache::swap(new Repository(new ArrayStore()));
+    session(['company' => 'co-1']);
+});
+
+afterEach(function () {
+    EloquentModel::unsetConnectionResolver();
+});
+
+function driverAssignVehicleDatabase(): SQLiteConnection
+{
+    $db = TrackingPageDatabase::boot();
+
+    $db->getSchemaBuilder()->create('users', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->timestamps();
+        $table->softDeletes();
+    });
+    $db->getSchemaBuilder()->create('drivers', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('user_uuid')->nullable();
+        $table->string('vehicle_uuid')->nullable();
+        $table->timestamps();
+        $table->softDeletes();
+    });
+
+    foreach (['user-1', 'user-2'] as $user) {
+        TrackingPageDatabase::insert($db, 'users', ['uuid' => $user, 'company_uuid' => 'co-1']);
+    }
+    TrackingPageDatabase::insert($db, 'drivers', ['uuid' => 'driver-1', 'company_uuid' => 'co-1', 'user_uuid' => 'user-1', 'vehicle_uuid' => 'vehicle-1']);
+    TrackingPageDatabase::insert($db, 'drivers', ['uuid' => 'driver-2', 'company_uuid' => 'co-1', 'user_uuid' => 'user-2']);
+
+    return $db;
+}
+
+function driverAssignVehicleVehicle(): Vehicle
+{
+    $vehicle = new Vehicle();
+    $vehicle->setRawAttributes(['uuid' => 'vehicle-1', 'company_uuid' => 'co-1'], true);
+    $vehicle->exists = true;
+
+    return $vehicle;
+}
+
+function driverAssignVehicleAssignments(SQLiteConnection $db): array
+{
+    return $db->table('drivers')->orderBy('uuid')->pluck('vehicle_uuid', 'uuid')->all();
+}
+
+test('assigning a driver the vehicle it already has keeps the assignment', function () {
+    $db = driverAssignVehicleDatabase();
+
+    Driver::where('uuid', 'driver-1')->first()->assignVehicle(driverAssignVehicleVehicle());
+
+    expect(driverAssignVehicleAssignments($db))->toBe(['driver-1' => 'vehicle-1', 'driver-2' => null]);
+});
+
+test('assigning a vehicle to another driver moves it from its current driver', function () {
+    $db = driverAssignVehicleDatabase();
+
+    $driver = Driver::where('uuid', 'driver-2')->first()->assignVehicle(driverAssignVehicleVehicle());
+
+    expect(driverAssignVehicleAssignments($db))->toBe(['driver-1' => null, 'driver-2' => 'vehicle-1'])
+        ->and($driver->vehicle->uuid)->toBe('vehicle-1');
+});

package/server/tests/Unit/Models/FleetTest.php

@@ -33,7 +33,8 @@ use Illuminate\Database\SQLiteConnection;
 use Spatie\Activitylog\LogOptions;
 use Spatie\Sluggable\SlugOptions;
 
-class FleetOpsFleetUnitCountingRelationFake
+// Extends the relation the model method now declares, so the override stays compatible; the parent constructor is skipped on purpose.
+class FleetOpsFleetUnitCountingRelationFake extends HasManyThrough
 {
     public array $wheres = [];
 
@@ -59,7 +60,7 @@ class FleetOpsFleetUnitCountingFake extends Fleet
     public array $driverRelations  = [];
     public array $vehicleRelations = [];
 
-    public function drivers()
+    public function drivers(): HasManyThrough
     {
         $relation                = new FleetOpsFleetUnitCountingRelationFake(5);
         $this->driverRelations[] = $relation;
@@ -67,7 +68,7 @@ class FleetOpsFleetUnitCountingFake extends Fleet
         return $relation;
     }
 
-    public function vehicles()
+    public function vehicles(): HasManyThrough
     {
         $relation                 = new FleetOpsFleetUnitCountingRelationFake(8);
         $this->vehicleRelations[] = $relation;