@fleetbase/fleetops-engine 0.6.57 → 0.6.59

package/server/tests/HOSConstraintContractsTest.php

@@ -0,0 +1,128 @@
+<?php
+
+use Fleetbase\FleetOps\Constraints\HOSConstraint;
+use Fleetbase\Models\ScheduleItem;
+use Illuminate\Support\Carbon;
+
+class FleetOpsHosScheduleItemFake extends ScheduleItem
+{
+    public int $duration;
+    public string $start_at;
+    public ?string $end_at         = null;
+    public ?string $break_start_at = null;
+    public ?string $break_end_at   = null;
+}
+
+function invokeFleetOpsHosConstraint(HOSConstraint $constraint, string $method, array $arguments = [])
+{
+    $reflection = new ReflectionMethod($constraint, $method);
+    $reflection->setAccessible(true);
+
+    return $reflection->invokeArgs($constraint, $arguments);
+}
+
+function fleetOpsScheduleItem(array $attributes): ScheduleItem
+{
+    $item = new FleetOpsHosScheduleItemFake();
+
+    foreach ($attributes as $key => $value) {
+        $item->{$key} = $value;
+    }
+
+    return $item;
+}
+
+function fleetOpsRecentScheduleItem(array $attributes): object
+{
+    return (object) $attributes;
+}
+
+test('hos constraint calculates driving hours across current and recent schedule items', function () {
+    $constraint = new HOSConstraint();
+    $current    = fleetOpsScheduleItem([
+        'duration' => 120,
+        'start_at' => '2026-07-19 12:00:00',
+    ]);
+    $recent     = collect([
+        fleetOpsRecentScheduleItem(['duration' => 90, 'start_at' => '2026-07-19 08:00:00']),
+        fleetOpsRecentScheduleItem(['duration' => 150, 'start_at' => '2026-07-19 10:00:00']),
+    ]);
+
+    expect(invokeFleetOpsHosConstraint($constraint, 'calculateTotalDrivingHours', [$current, $recent]))
+        ->toBe(6.0)
+        ->and(invokeFleetOpsHosConstraint($constraint, 'calculateDrivingHoursSince', [
+            $current,
+            $recent,
+            Carbon::parse('2026-07-19 09:00:00'),
+        ]))->toBe(4.5);
+});
+
+test('hos constraint enforces driving and weekly hour limits', function () {
+    $constraint = new HOSConstraint();
+    $current    = fleetOpsScheduleItem([
+        'duration' => 120,
+        'start_at' => '2026-07-19 12:00:00',
+    ]);
+
+    $withinLimit = collect([
+        fleetOpsRecentScheduleItem(['duration' => 300, 'start_at' => '2026-07-18 08:00:00']),
+        fleetOpsRecentScheduleItem(['duration' => 180, 'start_at' => '2026-07-17 08:00:00']),
+    ]);
+
+    $overLimit = collect([
+        fleetOpsRecentScheduleItem(['duration' => 600, 'start_at' => '2026-07-18 08:00:00']),
+        fleetOpsRecentScheduleItem(['duration' => 120, 'start_at' => '2026-07-17 08:00:00']),
+    ]);
+
+    $weeklyOverLimit = collect([
+        fleetOpsRecentScheduleItem(['duration' => 4200, 'start_at' => '2026-07-18 08:00:00']),
+        fleetOpsRecentScheduleItem(['duration' => 120, 'start_at' => '2026-07-01 08:00:00']),
+    ]);
+
+    expect(invokeFleetOpsHosConstraint($constraint, 'check11HourDrivingLimit', [$current, $withinLimit]))->toBeTrue()
+        ->and(invokeFleetOpsHosConstraint($constraint, 'check11HourDrivingLimit', [$current, $overLimit]))->toBeFalse()
+        ->and(invokeFleetOpsHosConstraint($constraint, 'check60_70HourWeeklyLimit', [$current, $withinLimit]))->toBeTrue()
+        ->and(invokeFleetOpsHosConstraint($constraint, 'check60_70HourWeeklyLimit', [$current, $weeklyOverLimit]))->toBeFalse();
+});
+
+test('hos constraint handles duty windows and thirty minute break requirements', function () {
+    $constraint = new HOSConstraint();
+    $current    = fleetOpsScheduleItem([
+        'duration'       => 120,
+        'start_at'       => '2026-07-19 12:00:00',
+        'end_at'         => '2026-07-19 14:00:00',
+        'break_start_at' => null,
+        'break_end_at'   => null,
+    ]);
+
+    $recentWithBreak = collect([
+        fleetOpsRecentScheduleItem([
+            'duration'       => 300,
+            'start_at'       => '2026-07-19 05:00:00',
+            'break_start_at' => '2026-07-19 08:00:00',
+            'break_end_at'   => '2026-07-19 08:30:00',
+        ]),
+    ]);
+
+    $recentWithoutBreak = collect([
+        fleetOpsRecentScheduleItem([
+            'duration'       => 420,
+            'start_at'       => '2026-07-19 05:00:00',
+            'break_start_at' => null,
+            'break_end_at'   => null,
+        ]),
+    ]);
+
+    $currentWithBreak = fleetOpsScheduleItem([
+        'duration'       => 120,
+        'start_at'       => '2026-07-19 12:00:00',
+        'end_at'         => '2026-07-19 14:00:00',
+        'break_start_at' => '2026-07-19 12:30:00',
+        'break_end_at'   => '2026-07-19 13:00:00',
+    ]);
+
+    expect(invokeFleetOpsHosConstraint($constraint, 'check14HourDutyWindow', [$current, collect()]))->toBeTrue()
+        ->and(invokeFleetOpsHosConstraint($constraint, 'check30MinuteBreak', [$current, $recentWithBreak]))->toBeTrue()
+        ->and(invokeFleetOpsHosConstraint($constraint, 'check30MinuteBreak', [$current, $recentWithoutBreak]))->toBeFalse()
+        ->and(invokeFleetOpsHosConstraint($constraint, 'check30MinuteBreak', [$currentWithBreak, $recentWithoutBreak]))->toBeTrue();
+});

package/server/tests/HubAndGettingStartedContractsTest.php

@@ -0,0 +1,158 @@
+<?php
+
+use Fleetbase\FleetOps\Http\Controllers\Internal\v1\HubController;
+use Fleetbase\FleetOps\Support\GettingStarted;
+use Fleetbase\Models\Company;
+use Illuminate\Http\Request;
+
+class FleetOpsHubControllerProbe extends HubController
+{
+    public function callHelper(string $method, mixed ...$arguments): mixed
+    {
+        $reflection = new ReflectionMethod(HubController::class, $method);
+        $reflection->setAccessible(true);
+
+        return $reflection->invoke($this, ...$arguments);
+    }
+}
+
+class FleetOpsGettingStartedProbe extends GettingStarted
+{
+    public function callHelper(string $method): array
+    {
+        $reflection = new ReflectionMethod(GettingStarted::class, $method);
+        $reflection->setAccessible(true);
+
+        return $reflection->invoke($this);
+    }
+}
+
+test('hub controller resource actions prioritize onboarding operational exceptions and healthy fallback', function () {
+    $controller = new FleetOpsHubControllerProbe();
+    $counts     = [
+        'drivers'                       => 0,
+        'vehicles'                      => 0,
+        'drivers_without_vehicles'      => 2,
+        'vehicles_without_drivers'      => 3,
+        'vehicles_without_devices'      => 4,
+        'unattached_devices'            => 5,
+        'resource_issues'               => 0,
+        'issues'                        => 1,
+        'overdue_vehicle_schedules'     => 0,
+        'upcoming_vehicle_schedules'    => 2,
+        'overdue_resource_work_orders'  => 0,
+        'open_resource_work_orders'     => 1,
+        'low_stock_parts'               => 2,
+        'unmatched_fuel_transactions'   => 3,
+        'fleets'                        => 0,
+        'places'                        => 0,
+        'vendors'                       => 0,
+        'contacts'                      => 0,
+    ];
+
+    $actions = $controller->callHelper('resourceActions', $counts, 0);
+
+    expect(array_column($actions, 'key'))->toBe([
+        'add_drivers',
+        'add_vehicles',
+        'attach_devices_to_vehicles',
+        'review_issues',
+        'prepare_vehicle_maintenance',
+        'review_open_work_orders',
+    ])
+        ->and($actions[2]['query'])->toEqual((object) ['attachment_state' => 'unattached'])
+        ->and($actions[3]['query'])->toEqual((object) ['status' => 'open']);
+
+    $healthyCounts                                 = array_map(fn () => 1, $counts);
+    $healthyCounts['drivers_without_vehicles']     = 0;
+    $healthyCounts['vehicles_without_drivers']     = 0;
+    $healthyCounts['vehicles_without_devices']     = 0;
+    $healthyCounts['unattached_devices']           = 0;
+    $healthyCounts['resource_issues']              = 0;
+    $healthyCounts['issues']                       = 0;
+    $healthyCounts['overdue_vehicle_schedules']    = 0;
+    $healthyCounts['upcoming_vehicle_schedules']   = 0;
+    $healthyCounts['overdue_resource_work_orders'] = 0;
+    $healthyCounts['open_resource_work_orders']    = 0;
+    $healthyCounts['low_stock_parts']              = 0;
+    $healthyCounts['unmatched_fuel_transactions']  = 0;
+
+    $ready = $controller->callHelper('resourceActions', $healthyCounts, 1);
+
+    expect($ready)->toHaveCount(1)
+        ->and($ready[0]['key'])->toBe('ready')
+        ->and($ready[0]['tone'])->toBe('success')
+        ->and($ready[0]['route'])->toBeNull();
+});
+
+test('hub controller maintenance actions summarize service priorities', function () {
+    $controller = new FleetOpsHubControllerProbe();
+
+    $actions = $controller->callHelper('maintenanceActions', 1, 2, 0, 3, 4, 5, 0);
+
+    expect(array_column($actions, 'key'))->toBe([
+        'overdue_schedules',
+        'overdue_work_orders',
+        'high_priority_maintenance',
+        'upcoming_service',
+        'no_open_work_orders',
+    ])
+        ->and($actions[0]['description'])->toContain('1 recurring service schedule is overdue')
+        ->and($actions[1]['description'])->toContain('3 work orders are past due');
+});
+
+test('hub controller small helpers build dashboard payload fragments', function () {
+    $controller = new FleetOpsHubControllerProbe();
+    session(['company' => 'company-session']);
+
+    $requestWithUser = new Request();
+    $requestWithUser->setUserResolver(fn () => (object) ['company_uuid' => 'user-company']);
+
+    expect($controller->callHelper('companyUuid', $requestWithUser))->toBe('company-session')
+        ->and($controller->callHelper('kpi', 'drivers', 'Drivers', 3, 'Ready', 'blue', 'id-card', 'management.drivers'))->toBe([
+            'key'     => 'drivers',
+            'label'   => 'Drivers',
+            'value'   => 3,
+            'caption' => 'Ready',
+            'tone'    => 'blue',
+            'icon'    => 'id-card',
+            'route'   => 'management.drivers',
+        ])
+        ->and($controller->callHelper('action', 'add', 'Add', 'Create records', 'info', 'plus', 'route.name', ['status' => 'open']))->toMatchArray([
+            'key'         => 'add',
+            'query'       => (object) ['status' => 'open'],
+        ])
+        ->and($controller->callHelper('link', 'Drivers', 'management.drivers', 'id-card', 4, 'Manage drivers'))->toBe([
+            'label'       => 'Drivers',
+            'route'       => 'management.drivers',
+            'icon'        => 'id-card',
+            'count'       => 4,
+            'description' => 'Manage drivers',
+        ])
+        ->and($controller->callHelper('doc', 'Drivers', 'id-card', 'fleet-ops/drivers', 'Drivers guide'))->toBe([
+            'label'       => 'Drivers',
+            'icon'        => 'id-card',
+            'slug'        => 'fleet-ops/drivers',
+            'title'       => 'Drivers guide',
+            'description' => '',
+        ]);
+});
+
+test('getting started recommendations expose the onboarding cards', function () {
+    $company = new Company(['uuid' => 'company-uuid']);
+    $helper  = new FleetOpsGettingStartedProbe($company);
+
+    $recommendations = $helper->callHelper('recommendations');
+
+    expect($recommendations)->toHaveCount(4)
+        ->and(array_column($recommendations, 'key'))->toBe([
+            'route_optimization',
+            'live_fleet',
+            'service_rates',
+            'customer_portal',
+        ])
+        ->and($recommendations[0])->toMatchArray([
+            'title'  => 'Route Optimization',
+            'accent' => 'blue',
+        ]);
+});

package/server/tests/ImportContractsTest.php

@@ -0,0 +1,191 @@
+<?php
+
+use Fleetbase\FleetOps\Imports\ContactImport;
+use Fleetbase\FleetOps\Imports\DriverImport;
+use Fleetbase\FleetOps\Imports\EquipmentImport;
+use Fleetbase\FleetOps\Imports\FleetImport;
+use Fleetbase\FleetOps\Imports\FuelReportImport;
+use Fleetbase\FleetOps\Imports\IssueImport;
+use Fleetbase\FleetOps\Imports\MaintenanceImport;
+use Fleetbase\FleetOps\Imports\MaintenanceScheduleImport;
+use Fleetbase\FleetOps\Imports\OrdersImport;
+use Fleetbase\FleetOps\Imports\PartImport;
+use Fleetbase\FleetOps\Imports\PlaceImport;
+use Fleetbase\FleetOps\Imports\VehicleExport as VehicleRowsImport;
+use Fleetbase\FleetOps\Imports\VehicleImport;
+use Fleetbase\FleetOps\Imports\VendorImport;
+use Fleetbase\FleetOps\Imports\WorkOrderImport;
+use Illuminate\Support\Collection;
+
+trait FleetOpsImportProbeRecorder
+{
+    public array $created = [];
+
+    protected function createFromImport(array $row): void
+    {
+        $this->created[] = $row;
+    }
+}
+
+class FleetOpsContactImportProbe extends ContactImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsDriverImportProbe extends DriverImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsEquipmentImportProbe extends EquipmentImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsFleetImportProbe extends FleetImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsFuelReportImportProbe extends FuelReportImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsIssueImportProbe extends IssueImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsMaintenanceImportProbe extends MaintenanceImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsMaintenanceScheduleImportProbe extends MaintenanceScheduleImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsPartImportProbe extends PartImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsPlaceImportProbe extends PlaceImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsVehicleImportProbe extends VehicleImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsVendorImportProbe extends VendorImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+class FleetOpsWorkOrderImportProbe extends WorkOrderImport
+{
+    use FleetOpsImportProbeRecorder;
+}
+
+test('pass through import adapters return the provided row collection', function () {
+    $rows = new Collection([
+        ['id' => 'row-1'],
+        ['id' => 'row-2'],
+    ]);
+
+    expect((new OrdersImport())->collection($rows))->toBe($rows)
+        ->and((new VehicleRowsImport())->collection($rows))->toBe($rows);
+});
+
+test('model backed import adapters create non empty rows and increment counters', function (string $class) {
+    $import = new $class();
+
+    $import->collection(new Collection([
+        new Collection(['name' => 'Valid row', 'empty' => null]),
+        new Collection(['name' => null, 'empty' => null]),
+        ['code' => 'array-row'],
+    ]));
+
+    expect($import->imported)->toBe(2)
+        ->and($import->created)->toBe([
+            ['name' => 'Valid row'],
+            ['code' => 'array-row'],
+        ]);
+})->with([
+    FleetOpsContactImportProbe::class,
+    FleetOpsDriverImportProbe::class,
+    FleetOpsEquipmentImportProbe::class,
+    FleetOpsFleetImportProbe::class,
+    FleetOpsFuelReportImportProbe::class,
+    FleetOpsIssueImportProbe::class,
+    FleetOpsMaintenanceImportProbe::class,
+    FleetOpsMaintenanceScheduleImportProbe::class,
+    FleetOpsPartImportProbe::class,
+    FleetOpsPlaceImportProbe::class,
+    FleetOpsVehicleImportProbe::class,
+    FleetOpsVendorImportProbe::class,
+    FleetOpsWorkOrderImportProbe::class,
+]);
+
+test('blank-row guarded imports skip empty spreadsheet rows before model creation', function () {
+    $guardedImports = [
+        'ContactImport.php',
+        'DriverImport.php',
+        'EquipmentImport.php',
+        'FleetImport.php',
+        'FuelReportImport.php',
+        'IssueImport.php',
+        'MaintenanceImport.php',
+        'MaintenanceScheduleImport.php',
+        'PartImport.php',
+        'PlaceImport.php',
+        'VehicleImport.php',
+        'VendorImport.php',
+        'WorkOrderImport.php',
+    ];
+
+    foreach ($guardedImports as $file) {
+        $source = file_get_contents(dirname(__DIR__) . '/src/Imports/' . $file);
+
+        expect($source)
+            ->toContain('if (empty($row))')
+            ->toContain('continue;')
+            ->toContain('$this->imported++');
+    }
+});
+
+test('all model-backed import adapters maintain imported row counters', function () {
+    $importsPath = dirname(__DIR__) . '/src/Imports';
+
+    foreach (glob($importsPath . '/*Import.php') as $path) {
+        if (!in_array(basename($path), [
+            'ContactImport.php',
+            'DriverImport.php',
+            'EquipmentImport.php',
+            'FleetImport.php',
+            'FuelReportImport.php',
+            'IssueImport.php',
+            'MaintenanceImport.php',
+            'MaintenanceScheduleImport.php',
+            'PartImport.php',
+            'PlaceImport.php',
+            'VehicleImport.php',
+            'VendorImport.php',
+            'WorkOrderImport.php',
+        ], true)) {
+            continue;
+        }
+
+        $source = file_get_contents($path);
+
+        expect($source)
+            ->toContain('public int $imported = 0;')
+            ->toContain('$this->imported++')
+            ->toContain('$this->createFromImport($row);');
+    }
+});