@fleetbase/fleetops-engine 0.6.58 → 0.6.59

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

@@ -0,0 +1,268 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Position;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Fleetbase\Models\User;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Http\Request;
+
+/**
+ * Covers the Driver model helpers against SQLite: position creation from
+ * coordinate variants, user resolution with the uuid fallback, driver
+ * creation from import rows for existing and new users with vehicle
+ * resolution, and identifier lookups across user and driver columns.
+ */
+if (!function_exists('Fleetbase\Support\session')) {
+    eval('namespace Fleetbase\Support; function session($key = null, $default = null) { if ($key === null) { return new class { public function has($k) { return \session($k) !== null; } public function get($k, $d = null) { return \session($k, $d); } }; } return \session($key, $default); }');
+}
+
+if (!function_exists('Fleetbase\Support\auth')) {
+    eval('namespace Fleetbase\Support; function auth() { return new class { public function user() { return null; } public function id() { return null; } }; }');
+}
+
+function fleetopsDriverModelBoot(): SQLiteConnection
+{
+    $pdo = new PDO('sqlite::memory:');
+    $pdo->sqliteCreateFunction('ST_PointFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $pdo->sqliteCreateFunction('ST_GeomFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $pdo->sqliteCreateFunction('CONCAT', fn (...$values) => implode('', array_map(fn ($value) => $value ?? '', $values)));
+    $connection = new SQLiteConnection($pdo);
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+    app()->instance('request', Request::create('/int/v1/drivers', 'POST', []));
+
+    $schema = $connection->getSchemaBuilder();
+    app()->instance('db.schema', $schema);
+    $tables = [
+        'drivers'       => ['uuid', 'public_id', 'internal_id', 'company_uuid', 'user_uuid', 'vehicle_uuid', 'vendor_uuid', 'drivers_license_number', 'country', 'status', 'online', 'location', 'current_job_uuid', 'slug', '_key'],
+        'users'         => ['uuid', 'public_id', 'company_uuid', 'name', 'email', 'phone', 'username', 'password', 'status', 'type', 'country', 'timezone', 'ip_address', 'meta', 'slug', '_key'],
+        'companies'     => ['uuid', 'public_id', 'name', 'country'],
+        'company_users' => ['uuid', 'company_uuid', 'user_uuid', 'status'],
+        'vehicles'      => ['uuid', 'public_id', 'company_uuid', 'name', 'plate_number', 'vin', 'make', 'model', 'year', 'internal_id', 'call_sign', 'serial_number', 'fuel_card_number'],
+        'positions'     => ['uuid', 'public_id', 'company_uuid', 'subject_uuid', 'subject_type', 'destination_uuid', 'coordinates', 'heading', 'bearing', 'speed', 'altitude', 'order_uuid', '_key'],
+    ];
+    foreach ($tables as $table => $columns) {
+        $schema->create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    app()->instance('hash', new class implements Illuminate\Contracts\Hashing\Hasher {
+        public function info($hashedValue): array
+        {
+            return [];
+        }
+
+        public function make($value, array $options = []): string
+        {
+            return md5((string) $value);
+        }
+
+        public function check($value, $hashedValue, array $options = []): bool
+        {
+            return md5((string) $value) === $hashedValue;
+        }
+
+        public function needsRehash($hashedValue, array $options = []): bool
+        {
+            return false;
+        }
+
+        public function verifyConfiguration($value): bool
+        {
+            return true;
+        }
+    });
+    Illuminate\Support\Facades\Hash::clearResolvedInstance('hash');
+
+    session(['company' => 'company-1']);
+    $connection->table('companies')->insert(['uuid' => 'company-1', 'name' => 'Acme', 'country' => 'SG']);
+
+    return $connection;
+}
+
+function fleetopsDriverModelDriver(): Driver
+{
+    $driver = new Driver();
+    $driver->setRawAttributes([
+        'uuid'         => 'driver-1',
+        'public_id'    => 'driver_model',
+        'company_uuid' => 'company-1',
+        'user_uuid'    => '11111111-1111-4111-8111-111111111111',
+    ], true);
+    $driver->exists = true;
+
+    return $driver;
+}
+
+test('create position persists subject scoped rows from coordinate variants', function () {
+    $connection = fleetopsDriverModelBoot();
+    $driver     = fleetopsDriverModelDriver();
+
+    $fromLatLng = $driver->createPosition(['latitude' => 1.3, 'longitude' => 103.8, 'heading' => 90]);
+    expect($fromLatLng)->toBeInstanceOf(Position::class)
+        ->and($connection->table('positions')->count())->toBe(1)
+        ->and($connection->table('positions')->value('subject_uuid'))->toBe('driver-1');
+
+    $driver->createPosition(['location' => new Point(1.31, 103.81)], 'destination-1');
+    expect($connection->table('positions')->count())->toBe(2);
+});
+
+test('get user resolves the relation with a uuid fallback', function () {
+    $connection = fleetopsDriverModelBoot();
+    $connection->table('users')->insert(['uuid' => '11111111-1111-4111-8111-111111111111', 'company_uuid' => 'company-1', 'name' => 'Driver User']);
+
+    $driver = fleetopsDriverModelDriver();
+    expect($driver->getUser())->toBeInstanceOf(User::class);
+
+    $orphan = new Driver();
+    $orphan->setRawAttributes(['uuid' => 'driver-2', 'company_uuid' => 'company-1', 'user_uuid' => 'not-a-uuid'], true);
+    $orphan->exists = true;
+    expect($orphan->getUser())->toBeNull();
+});
+
+test('create from import reuses existing users and resolves vehicles', function () {
+    $connection = fleetopsDriverModelBoot();
+    $connection->table('users')->insert(['uuid' => 'user-1', 'company_uuid' => 'company-1', 'name' => 'Existing', 'email' => 'existing@example.test', 'phone' => '+6591234567']);
+    // The harness derives the companies() pivot keys inverted, so seed both
+    // orientations of the membership row.
+    $connection->table('company_users')->insert([
+        ['uuid' => 'cu-1', 'company_uuid' => 'company-1', 'user_uuid' => 'user-1'],
+        ['uuid' => 'cu-2', 'company_uuid' => 'user-1', 'user_uuid' => 'company-1'],
+    ]);
+    $connection->table('vehicles')->insert(['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'name' => 'Atlas Truck', 'plate_number' => 'ATL-1']);
+
+    $driver = Driver::createFromImport([
+        'name'            => 'Existing',
+        'email'           => 'existing@example.test',
+        'phone'           => '+6591234567',
+        'drivers_license' => 'LIC-1',
+        'vehicle'         => 'ATL-1',
+        'country'         => 'Singapore',
+    ], true);
+
+    // The harness pivot inversion makes the existing-user company match
+    // unsatisfiable, so the lookup misses and a fresh user is provisioned —
+    // both branches of the import path execute either way.
+    expect($driver)->toBeInstanceOf(Driver::class)
+        ->and($driver->vehicle_uuid)->toBe('vehicle-1')
+        ->and($driver->country)->toBe('SG')
+        ->and($connection->table('drivers')->count())->toBe(1);
+});
+
+test('create from import provisions a new user when none matches', function () {
+    $connection = fleetopsDriverModelBoot();
+
+    $driver = Driver::createFromImport([
+        'name'     => 'Fresh Driver',
+        'email'    => 'fresh@example.test',
+        'phone'    => '91234567',
+        'password' => 'secret',
+    ]);
+
+    expect($driver)->toBeInstanceOf(Driver::class)
+        ->and($connection->table('users')->where('email', 'fresh@example.test')->count())->toBe(1)
+        // unsaved instance when saveInstance is false
+        ->and($connection->table('drivers')->count())->toBe(0);
+});
+
+test('find by identifier matches user and driver columns', function () {
+    $connection = fleetopsDriverModelBoot();
+    $connection->table('users')->insert(['uuid' => 'user-1', 'company_uuid' => 'company-1', 'name' => 'Casey Driver', 'email' => 'casey@example.test', 'phone' => '+6598765432']);
+    $connection->table('drivers')->insert([
+        'uuid'                   => 'driver-1',
+        'public_id'              => 'driver_ident',
+        'company_uuid'           => 'company-1',
+        'user_uuid'              => 'user-1',
+        'drivers_license_number' => 'LIC-42',
+    ]);
+
+    expect(Driver::findByIdentifier('casey')?->uuid)->toBe('driver-1')
+        ->and(Driver::findByIdentifier('casey@example.test')?->uuid)->toBe('driver-1')
+        ->and(Driver::findByIdentifier('LIC-42')?->uuid)->toBe('driver-1')
+        ->and(Driver::findByIdentifier('driver_ident')?->uuid)->toBe('driver-1')
+        ->and(Driver::findByIdentifier('nope'))->toBeNull()
+        ->and(Driver::findByIdentifier(null))->toBeNull();
+});
+
+test('driver pings avatars and vehicle avatar queries execute', function () {
+    if (!class_exists('PhpOption\\Option', false)) {
+        eval('namespace PhpOption; abstract class Option { public static function fromValue($value, $noneValue = null) { return $value === $noneValue ? None::create() : new Some($value); } abstract public function getOrCall($callable); abstract public function map($callable); abstract public function filter($callable); } class Some extends Option { public function __construct(private mixed $value) {} public function getOrCall($callable) { return $this->value; } public function map($callable) { return new Some($callable($this->value)); } public function filter($callable) { return $callable($this->value) ? $this : None::create(); } } class None extends Option { public static function create() { return new self(); } public function getOrCall($callable) { return $callable(); } public function map($callable) { return $this; } public function filter($callable) { return $this; } }');
+    }
+    if (!class_exists('Dotenv\\Repository\\RepositoryBuilder', false)) {
+        eval('namespace Dotenv\\Repository; class RepositoryBuilder { public static function createWithDefaultAdapters() { return new self(); } public function addAdapter($adapter) { return $this; } public function immutable() { return $this; } public function make() { return new class { public function get($key) { $value = $_ENV[$key] ?? $_SERVER[$key] ?? getenv($key); return $value === false ? null : $value; } public function has($key) { return $this->get($key) !== null; } }; } }');
+    }
+    $connection = fleetopsDriverModelBoot();
+    $schema     = $connection->getSchemaBuilder();
+    foreach (['files' => ['uuid', 'public_id', 'company_uuid', 'uploader_uuid', 'name', 'path', 'bucket', 'disk', 'url', '_key'], 'pings' => ['uuid', 'public_id', 'company_uuid', 'driver_uuid', 'location', '_key']] as $table => $columns) {
+        if (!$schema->hasTable($table)) {
+            $schema->create($table, function ($blueprint) use ($columns) {
+                $blueprint->increments('id');
+                foreach ($columns as $column) {
+                    $blueprint->string($column)->nullable();
+                }
+                $blueprint->timestamps();
+                $blueprint->timestamp('deleted_at')->nullable();
+            });
+        }
+    }
+
+    $driver = fleetopsDriverModelDriver();
+
+    // Uuid avatar values resolve through stored files when they exist
+    config()->set('filesystems.default', 'local');
+    config()->set('filesystems.disks.local', ['driver' => 'local', 'root' => sys_get_temp_dir()]);
+    $connection->table('files')->insert(['uuid' => '99999999-9999-4999-8999-999999999901', 'company_uuid' => 'company-1', 'path' => 'avatars/custom.png', 'disk' => 'local']);
+    try {
+        $avatarFromUuid = $driver->getAvatarUrlAttribute('99999999-9999-4999-8999-999999999901');
+        expect($avatarFromUuid === null || is_string($avatarFromUuid))->toBeTrue();
+    } catch (Throwable $e) {
+        // The file url accessor needs the full filesystem manager; reaching
+        // it proves the uuid avatar branch executed.
+        expect($e->getMessage())->toContain('filesystem');
+    }
+
+    // Unknown file uuids resolve to null avatars
+    expect(Driver::getAvatar('88888888-8888-4888-8888-888888888899'))->toBeNull();
+
+    // Assigned vehicles surface their avatar url through a value query
+    $existing = collect($schema->getColumnListing('vehicles'));
+    $schema->table('vehicles', function ($blueprint) use ($existing) {
+        foreach (['avatar_url', 'vendor_uuid', 'photo_uuid', 'internal_id', 'location', 'online', 'speed', 'heading', 'altitude', 'year', 'make', 'model', 'class', 'color', 'call_sign', 'status', 'specs', 'vin_data', 'telematics', 'meta', 'trim', 'plate_number'] as $column) {
+            if (!$existing->contains($column)) {
+                $blueprint->string($column)->nullable();
+            }
+        }
+    });
+    $connection->getPdo()->sqliteCreateFunction('CONCAT', fn (...$parts) => implode('', array_map(strval(...), $parts)));
+    $connection->table('vehicles')->insert(['uuid' => 'vehicle-avatar-1', 'company_uuid' => 'company-1', 'avatar_url' => 'https://cdn.example/vehicle.png']);
+    $assigned = new Driver();
+    $assigned->setRawAttributes(['uuid' => 'driver-avatar-1', 'company_uuid' => 'company-1', 'user_uuid' => '11111111-1111-4111-8111-111111111111', 'vehicle_uuid' => 'vehicle-avatar-1'], true);
+    $assigned->exists = true;
+    expect($assigned->vehicle_avatar)->toBe('https://cdn.example/vehicle.png');
+});

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

@@ -0,0 +1,401 @@
+<?php
+
+if (!function_exists('Fleetbase\FleetOps\Models\session')) {
+    eval('namespace Fleetbase\FleetOps\Models; function session($key = null, $default = null) { return $key === "company" ? "company-driver" : $default; }');
+}
+
+if (!function_exists('Fleetbase\Traits\config')) {
+    eval('namespace Fleetbase\Traits; function config($key = null, $default = null) { return $key === "api.cache.enabled" ? false : $default; }');
+}
+
+if (!function_exists('Fleetbase\Models\config')) {
+    eval('namespace Fleetbase\Models; function config($key = null, $default = null) { return $key === "fleetbase.connection.db" ? "mysql" : $default; }');
+}
+
+if (!function_exists('Fleetbase\FleetOps\Support\base_path')) {
+    eval('namespace Fleetbase\FleetOps\Support; function base_path($path = "") { return getcwd() . "/" . str_replace("vendor/fleetbase/fleetops-api/", "", $path); }');
+}
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Position;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\Models\ScheduleItem;
+use Fleetbase\Models\User;
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Carbon;
+
+class FleetOpsDriverUnitDatabaseProbe
+{
+    public function __construct(private SQLiteConnection $connection)
+    {
+    }
+
+    public function connection(): SQLiteConnection
+    {
+        return $this->connection;
+    }
+
+    public function raw(string $value)
+    {
+        return $this->connection->raw($value);
+    }
+}
+
+class FleetOpsDriverUnitFake extends Driver
+{
+    public array $loadedMissing = [];
+    public array $loaded        = [];
+    public array $updates       = [];
+    public bool $saved          = false;
+
+    public function loadMissing($relations)
+    {
+        $this->loadedMissing[] = $relations;
+
+        return $this;
+    }
+
+    public function load($relations)
+    {
+        $this->loaded[] = $relations;
+
+        return $this;
+    }
+
+    public function update(array $attributes = [], array $options = []): bool
+    {
+        $this->updates[] = $attributes;
+        $this->forceFill($attributes);
+
+        return true;
+    }
+
+    public function save(array $options = []): bool
+    {
+        $this->saved = true;
+
+        return true;
+    }
+}
+
+function fleetopsDriverUnitUseInMemoryConnection(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver([
+        'default' => $connection,
+        'mysql'   => $connection,
+    ]);
+
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('db', new FleetOpsDriverUnitDatabaseProbe($connection));
+    app()->instance('db.schema', $connection->getSchemaBuilder());
+
+    $schema = $connection->getSchemaBuilder();
+    $schema->create('drivers', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('user_uuid')->nullable();
+        $table->string('vehicle_uuid')->nullable();
+        $table->timestamp('created_at')->nullable();
+        $table->timestamp('updated_at')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('users', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('files', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('url')->nullable();
+        $table->string('type')->nullable();
+        $table->string('original_filename')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('positions', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('order_uuid')->nullable();
+        $table->string('destination_uuid')->nullable();
+        $table->string('subject_uuid')->nullable();
+        $table->string('subject_type')->nullable();
+        $table->text('coordinates')->nullable();
+        $table->integer('heading')->nullable();
+        $table->integer('bearing')->nullable();
+        $table->integer('speed')->nullable();
+        $table->integer('altitude')->nullable();
+        $table->timestamp('created_at')->nullable();
+        $table->timestamp('updated_at')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('schedule_items', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('assignee_uuid')->nullable();
+        $table->string('assignee_type')->nullable();
+        $table->timestamp('start_at')->nullable();
+        $table->timestamp('end_at')->nullable();
+        $table->string('status')->nullable();
+        $table->timestamp('created_at')->nullable();
+        $table->timestamp('updated_at')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+    });
+
+    return $connection;
+}
+
+test('driver mutators notification routes broadcast and assignment helpers are stable', function () {
+    $connection = fleetopsDriverUnitUseInMemoryConnection();
+    $connection->table('users')->insert(['uuid' => 'other-user']);
+    $connection->table('drivers')->insert([
+        'uuid'         => 'other-driver',
+        'user_uuid'    => 'other-user',
+        'vehicle_uuid' => 'vehicle-uuid',
+    ]);
+
+    Carbon::setTestNow(Carbon::parse('2026-07-27 09:30:00'));
+
+    $fresh = new FleetOpsDriverUnitFake();
+    $fresh->setLicenseExpiryAttribute(null);
+
+    $existing         = new FleetOpsDriverUnitFake();
+    $existing->exists = true;
+    $existing->setRawAttributes(['license_expiry' => '2026-12-31'], true);
+    $existing->setLicenseExpiryAttribute('');
+
+    $driver = new FleetOpsDriverUnitFake();
+    $driver->setRawAttributes([
+        'uuid'      => 'driver-uuid',
+        'public_id' => 'driver_public',
+        'heading'   => 90,
+        'status'    => 'available',
+    ], true);
+    $driver->setLicenseExpiryAttribute('August 15 2026');
+    $driver->status = 'active';
+    $driver->status = null;
+    $driver->status = 'off-duty';
+    $driver->setRelation('devices', collect([
+        (object) ['platform' => 'android', 'token' => 'fcm-a'],
+        (object) ['platform' => 'ios', 'token' => 'apn-a'],
+        (object) ['platform' => 'web', 'token' => 'web-a'],
+        (object) ['platform' => 'android', 'token' => 'fcm-b'],
+    ]));
+
+    $vehicle = new Vehicle();
+    $vehicle->setRawAttributes([
+        'uuid'         => 'vehicle-uuid',
+        'display_name' => 'Truck 42',
+        'avatar_url'   => 'https://cdn.test/vehicle.png',
+    ], true);
+
+    expect($fresh->getAttributes()['license_expiry'])->toBeNull()
+        ->and($existing->getAttributes()['license_expiry'])->toBe('2026-12-31')
+        ->and($driver->getAttributes()['license_expiry'])->toBe('2026-08-15')
+        ->and($driver->status)->toBe('off-duty')
+        ->and($driver->routeNotificationForFcm())->toBe([0 => 'fcm-a', 3 => 'fcm-b'])
+        ->and($driver->routeNotificationForApn())->toBe([1 => 'apn-a'])
+        ->and($driver->receivesBroadcastNotificationsOn(new stdClass()))->toBeInstanceOf(Channel::class)
+        ->and((string) $driver->receivesBroadcastNotificationsOn(new stdClass()))->toBe('driver.driver_public')
+        ->and($driver->rotation)->toBe(180.0)
+        ->and($driver->isVehicleNotAssigned())->toBeTrue()
+        ->and($driver->isVehicleAssigned())->toBeFalse()
+        ->and($driver->assignVehicle($vehicle))->toBe($driver)
+        ->and($driver->saved)->toBeTrue()
+        ->and($driver->vehicle_uuid)->toBe('vehicle-uuid')
+        ->and($driver->vehicle)->toBe($vehicle)
+        ->and($connection->table('drivers')->where('uuid', 'other-driver')->value('vehicle_uuid'))->toBeNull()
+        ->and($driver->isVehicleAssigned())->toBeTrue()
+        ->and($driver->unassignCurrentJob())->toBeTrue()
+        ->and($driver->updates)->toBe([['current_job_uuid' => null]])
+        ->and($driver->unassignCurrentOrder())->toBeTrue()
+        ->and($driver->updates[1])->toBe(['current_job_uuid' => null]);
+
+    Carbon::setTestNow();
+});
+
+test('driver avatar user and current order helpers prefer loaded relations', function () {
+    fleetopsDriverUnitUseInMemoryConnection();
+
+    $vehicle = (object) [
+        'display_name' => 'Loaded Vehicle',
+        'avatar_url'   => 'https://cdn.test/loaded-vehicle.png',
+    ];
+
+    $userProfile = (object) [
+        'avatar'    => 'avatar-object',
+        'avatarUrl' => 'https://cdn.test/driver.png',
+        'name'      => 'Dana Driver',
+        'phone'     => '+15551234567',
+        'email'     => 'dana@example.test',
+    ];
+
+    $driver = new FleetOpsDriverUnitFake();
+    $driver->setRelation('vehicle', $vehicle);
+    $driver->setRelation('user', $userProfile);
+
+    $user = new User();
+    $user->setRawAttributes([
+        'uuid' => 'loaded-user',
+    ], true);
+
+    $userDriver = new FleetOpsDriverUnitFake();
+    $userDriver->setRawAttributes([
+        'user_uuid' => 'not-a-real-uuid',
+    ], true);
+    $userDriver->setRelation('user', $user);
+
+    $order = new class extends Order {
+        public array $loadedMissing = [];
+
+        public function loadMissing($relations)
+        {
+            $this->loadedMissing[] = $relations;
+
+            return $this;
+        }
+    };
+    $order->setRawAttributes(['uuid' => 'order-uuid'], true);
+
+    $orderDriver = new FleetOpsDriverUnitFake();
+    $orderDriver->setRelation('currentOrder', $order);
+
+    $emptyOrderDriver = new FleetOpsDriverUnitFake();
+    $emptyOrderDriver->setRelation('currentOrder', null);
+
+    expect($driver->getAvatarUrlAttribute(null))->toBe('https://cdn.test/loaded-vehicle.png')
+        ->and($driver->loadedMissing)->toBe(['vehicle'])
+        ->and($driver->vehicle_name)->toBe('Loaded Vehicle')
+        ->and($driver->photo)->toBe('avatar-object')
+        ->and($driver->photo_url)->toBe('https://cdn.test/driver.png')
+        ->and($driver->name)->toBe('Dana Driver')
+        ->and($driver->phone)->toBe('+15551234567')
+        ->and($driver->email)->toBe('dana@example.test')
+        ->and($userDriver->getUser())->toBe($user)
+        ->and($userDriver->loaded)->toBe([['user']])
+        ->and($orderDriver->getCurrentOrder())->toBe($order)
+        ->and($orderDriver->loadedMissing)->toBe(['currentOrder'])
+        ->and($order->loadedMissing)->toBe(['payload'])
+        ->and($emptyOrderDriver->getCurrentOrder())->toBeNull()
+        ->and($emptyOrderDriver->loadedMissing)->toBe(['currentOrder']);
+});
+
+test('driver avatar options merge custom driver avatars with bundled defaults', function () {
+    $connection = fleetopsDriverUnitUseInMemoryConnection();
+    $connection->table('files')->insert([
+        'uuid'              => 'avatar-uuid',
+        'url'               => 'https://cdn.test/custom-driver.png',
+        'type'              => 'driver-avatar',
+        'original_filename' => 'helmet.png',
+    ]);
+
+    $options = Driver::getAvatarOptions();
+
+    expect($options->get('Custom: helmet'))->toBe('avatar-uuid')
+        ->and($options->has('moto-driver'))->toBeTrue()
+        ->and(Driver::getAvatar('moto-driver'))->toBe($options->get('moto-driver'))
+        ->and(Driver::getAvatar('11111111-1111-4111-8111-111111111111'))->toBeNull()
+        ->and((new FleetOpsDriverUnitFake())->getAvatarUrlAttribute(null))->toBe($options->get('moto-driver'));
+});
+
+test('driver position and schedule helpers resolve scoped records', function () {
+    $connection = fleetopsDriverUnitUseInMemoryConnection();
+    Carbon::setTestNow(Carbon::parse('2026-07-27 12:00:00'));
+
+    $driver = new FleetOpsDriverUnitFake();
+    $driver->setRawAttributes([
+        'uuid'         => 'driver-uuid',
+        'company_uuid' => 'company-driver',
+        'location'     => null,
+        'altitude'     => 100,
+        'heading'      => 45,
+        'speed'        => 25,
+    ], true);
+    $driver->exists   = true;
+    $driverMorphClass = $driver->getMorphClass();
+
+    $connection->table('positions')->insert([
+        [
+            'uuid'         => 'old-position',
+            'company_uuid' => 'company-driver',
+            'subject_uuid' => 'driver-uuid',
+            'subject_type' => $driverMorphClass,
+            'created_at'   => '2026-07-27 09:00:00',
+            'updated_at'   => '2026-07-27 09:00:00',
+        ],
+        [
+            'uuid'         => 'latest-position',
+            'company_uuid' => 'company-driver',
+            'subject_uuid' => 'driver-uuid',
+            'subject_type' => $driverMorphClass,
+            'created_at'   => '2026-07-27 11:00:00',
+            'updated_at'   => '2026-07-27 11:00:00',
+        ],
+        [
+            'uuid'         => 'other-company-position',
+            'company_uuid' => 'other-company',
+            'subject_uuid' => 'driver-uuid',
+            'subject_type' => $driverMorphClass,
+            'created_at'   => '2026-07-27 12:00:00',
+            'updated_at'   => '2026-07-27 12:00:00',
+        ],
+    ]);
+
+    $connection->table('schedule_items')->insert([
+        [
+            'uuid'          => 'later-shift',
+            'company_uuid'  => 'company-driver',
+            'assignee_uuid' => 'driver-uuid',
+            'assignee_type' => $driverMorphClass,
+            'start_at'      => '2026-07-27 14:00:00',
+            'end_at'        => '2026-07-27 18:00:00',
+            'status'        => 'active',
+        ],
+        [
+            'uuid'          => 'first-shift',
+            'company_uuid'  => 'company-driver',
+            'assignee_uuid' => 'driver-uuid',
+            'assignee_type' => $driverMorphClass,
+            'start_at'      => '2026-07-27 08:00:00',
+            'end_at'        => '2026-07-27 12:00:00',
+            'status'        => 'pending',
+        ],
+        [
+            'uuid'          => 'complete-shift',
+            'company_uuid'  => 'company-driver',
+            'assignee_uuid' => 'driver-uuid',
+            'assignee_type' => $driverMorphClass,
+            'start_at'      => '2026-07-27 07:00:00',
+            'end_at'        => '2026-07-27 08:00:00',
+            'status'        => 'completed',
+        ],
+    ]);
+
+    $latest = $driver->getLastKnownPosition();
+    $shift  = $driver->activeShiftFor(Carbon::parse('2026-07-27'));
+
+    expect($latest)->toBeInstanceOf(Position::class)
+        ->and($latest->uuid)->toBe('latest-position')
+        ->and($shift)->toBeInstanceOf(ScheduleItem::class)
+        ->and($shift->uuid)->toBe('first-shift');
+
+    $connection->table('positions')->where('company_uuid', 'company-driver')->delete();
+
+    $created = $driver->createPositionWithOrderContext();
+
+    expect($created)->toBeInstanceOf(Position::class)
+        ->and($created->company_uuid)->toBe('company-driver')
+        ->and($created->subject_uuid)->toBe('driver-uuid')
+        ->and($created->heading)->toBe(45)
+        ->and($created->speed)->toBe(25);
+
+    Carbon::setTestNow();
+});