Improve Fleet-Ops server test coverage

[roncodes]

Summary

This is a progressive backend-only coverage PR for Fleet-Ops ./server.

• Wires backend coverage reporting into the Composer workflow with a 100% fail-under gate.
• Expands categorized server tests under server/tests/Unit/... and server/tests/Feature/... instead of adding more flat root-level coverage files.
• Adds coverage for exports, imports, value objects, events, exceptions, registries, analytics options, mail, notifications, provider registration contracts, driver model helpers, internal driver controller helpers, and LiveController operations monitor snapshot behavior.
• Extends the shared test bootstrap with additive shims so controller error branches (response()->apiError(...)) and job dispatch branches (Job::dispatch/dispatchIf) are reachable under test — previously these fatally errored and structurally blocked coverage on nearly every controller.
• Covers the API DriverController protected helper methods, the self-contained route/order driving-simulation methods (no-route and successful-dispatch branches), and the driver-lookup/organization not-found error branches via an in-memory SQLite fixture.

Latest Local Coverage

Fresh host run from COMPOSER_PROCESS_TIMEOUT=0 composer coverage:baseline:

Metric	Coverage	Covered / Total
Lines	99.26%	33,872 / 34,124 statements
Methods	96.04%	4,174 / 4,346 methods
Classes	77.93%	406 / 521 classes

Coverage gate verification:

• php scripts/coverage-summary.php coverage/clover.xml --fail-under=100 correctly fails while coverage is below 100%.
• The fail-under gate remains red by design until backend line coverage reaches 100%.

Latest Progress

• Line coverage is 99.26%, up from 79.53% at the start of this campaign. The last stretch came from pattern sweeps — one data-driven test per repeated code shape — covering export collection() scoping (17 classes), queryWithRequest across every API controller (19 classes), import createFromImport delegation (13 classes), filter date ranges, Excel download/import seams, request authorize() gates, resource relation resolution, observer/listener query seams, and assorted controller/command/job seams.
• Twelve production bugs found and fixed. Highlights: Place::insertFromCoordinates() guarded empty reverse-geocoding results with !$results->count() === 0, comparing a bool to an int so the guard never fired — with no results the code fell through to an address array carrying location 0,0, which array_merge layered over the caller's real coordinates, silently inserting places at Null Island instead of returning false as documented. Lalamove::getQuotationForMarket() called instance(null, null, $market), putting the market in the bool $sandbox slot — without strict_types the string coerced to true, so market-scoped quotations ran against the sandbox host with the market silently dropped. OrderConfig::default() declared a non-nullable self return while returning first(), so companies without a stored transport config fataled instead of having one provisioned. ServiceRate called Collection::sortByDesc() with no argument, throwing whenever a parcel outsized every fee tier.
• Remaining residue (~390 statements) concentrates in the deep internal/api Order, Driver and Orchestration controller flows, the shared queryWithRequest pipeline, and harness-unreachable defensive catches.

Validation

Run on the host runtime (asdf PHP 8.4 with Xdebug, XDEBUG_MODE=coverage), no Docker:

• php -l server/tests/Feature/Http/Api/DriverControllerHelpersTest.php
• php scripts/pest-runner.php server/tests/Feature/Http/Api/DriverControllerHelpersTest.php
• vendor/bin/php-cs-fixer fix --using-cache=no --sequential server/tests/Feature/Http/Api/DriverControllerHelpersTest.php scripts/pest-bootstrap.php
• composer test:lint
• composer test:unit
• COMPOSER_PROCESS_TIMEOUT=0 composer coverage:baseline
• php scripts/coverage-summary.php coverage/clover.xml --fail-under=100
• git diff --check
• git diff --cached --check

Current Lowest Coverage Targets

Next backend coverage slices, from the fresh local Clover report (highest absolute uncovered):

File	Uncovered statements
server/src/Http/Controllers/Api/v1/OrderController.php	21
server/src/Http/Controllers/Internal/v1/OrchestrationController.php	19
server/src/Http/Controllers/Api/v1/DriverController.php	16
server/src/Models/Place.php	15
server/src/Http/Controllers/Internal/v1/OrderController.php	7

A growing share of what remains is provably unreachable rather than merely untested — shadowed instanceof chains (the spatial casts check GeometryInterface before each concrete type), ?type returns that never actually yield null (Find::httpResourceForModel always falls back to FleetbaseResource), and guards whose conditions cannot evaluate true. These are documented in the tests that probe them.

Practical ceiling

A growing share of what remains is provably unreachable rather than untested. Confirmed by direct analysis so far:

Location	Why it cannot execute
Casts/{Point,Polygon,MultiPolygon}	instanceof GeometryInterface (or Expression) is tested before each concrete spatial type, so the later arms are shadowed
Http/Resources/v1/{Maintenance,MaintenanceSchedule,WorkOrder,Order}	Find::httpResourceForModel() always resolves a class, falling back to FleetbaseResource, so the JsonResource fallbacks never run
Models/Place::createFromMixed	re-tests isCoordinatesStrict() inside a branch already gated on it
Models/Place::findExistingSharedPlace	$location is initialised to a SpatialPoint and the catch assigns one, so the non-point guard cannot fire
Support/Utils::coordsToCircle	the 0..360 loop closes the circle exactly, so the closing-point guard never triggers
Http/Controllers/Internal/v1/GeocoderController	guards the result of getPointFromCoordinates(), declared : Point (non-nullable)
Http/Controllers/Internal/v1/MetricsController	guards $request->date() against not being a DateTime; it returns Carbon, which extends it
Http/Controllers/Api/v1/DriverController	null-company fallback sits after the same variable is already dereferenced
Integrations/Lalamove::__callStatic	instance is a defined public static, so PHP never routes it through __callStatic

Two things previously written off as untestable turned out not to be, and are now covered: the queryWithRequest seam on all 19 API controllers (it needed only a session store, route-resolver stub and a couple of request macros), and the Lalamove API response handling (its post/request helpers are private, but the Guzzle client is an injectable property, so a MockHandler exercises the real code path without network access).

Two further lines (Internal/v1/OrderController 887-888) are reachable only once the upstream findByIdOrFail defect above is fixed, and are deliberately left uncovered rather than shimmed green.

A handful more are blocked by genuinely external dependencies — Firebase-backed push payloads, the Illuminate\Encryption\Encrypter (absent from this vendor tree), and MySQL-only st_distance_sphere spatial predicates that SQLite cannot evaluate.

Known upstream defect (needs a core-api patch)

Model::findByIdOrFail() in fleetbase/core-api throws BadMethodCallException instead of the ModelNotFoundException it documents, because it calls a getModelNotFoundException() method that does not exist on Eloquent's Builder. Four call sites in this package have catch (ModelNotFoundException) blocks that can never fire, so missing records surface as HTTP 500s. Details, affected lines and a suggested fix are in this PR comment. Two lines in Internal/v1/OrderController.php are intentionally left uncovered pending that fix rather than shimmed green.

Notes

• This PR is intentionally still progressive and remains below the 100% final target.
• Local validation is run before every push so broken test slices are not published.
• Coverage work is pushed in batches of a few validated commits so progress is not stranded locally.
• The largest remaining uncovered surfaces are the big API/Internal Order and Driver controllers; many of their error/dispatch branches are now reachable thanks to the bootstrap shim additions.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

[roncodes]

Upstream defect found during this coverage work — needs a core-api patch

Not fixable in this PR (the code lives in the fleetbase/core-api dependency), recording it here so it isn't lost.

What

Fleetbase\Models\Model::findByIdOrFail() — core-api/src/Models/Model.php:224 — ends with:

throw (new static())->newModelQuery()->getModel()->newQuery()->getModel()::query()
    ->getModel()::query()->getModelNotFoundException($cls, [$identifier]);

getModelNotFoundException() does not exist on Illuminate\Database\Eloquent\Builder. It appears nowhere in illuminate/*.

Effect

The method's own docblock declares @throws \Illuminate\Database\Eloquent\ModelNotFoundException, but a missing record actually raises:

BadMethodCallException: Call to undefined method Illuminate\Database\Eloquent\Builder::getModelNotFoundException()

Confirmed at runtime, not just by reading — calling Vendor::findByIdOrFail('vendor_does_not_exist') against a seeded schema throws the BadMethodCallException.

Why it matters for Fleet-Ops

Callers that follow the documented contract wrap the call in catch (ModelNotFoundException $e). Those catch blocks can never fire, so a lookup for a nonexistent record escapes as an uncaught BadMethodCallException (HTTP 500) instead of the intended not-found response.

Affected call sites in this package:

File	Line	Consequence
server/src/Http/Controllers/Internal/v1/OrderController.php	886	nextActivity — catch (ModelNotFoundException) returning 'No order found.' is dead; unknown order id 500s
server/src/Http/Controllers/Internal/v1/OrderController.php	1417	findOrderForDriverPing
server/src/Http/Controllers/Internal/v1/VendorController.php	313	vendor lookup
server/src/Http/Controllers/Internal/v1/VendorController.php	318	contact lookup

Suggested fix (in core-api)

Throw the exception directly rather than routing through a nonexistent builder method:

throw (new ModelNotFoundException())->setModel(static::class, [$identifier]);

Coverage note

The two lines at Internal/v1/OrderController.php:887-888 are deliberately left uncovered in this PR. They are reachable only if findByIdOrFail throws what it documents. A test-harness shim could make them green, but that would hide a defect that is still live in production, so they remain uncovered pending the upstream fix.

[roncodes]

Second defect found during coverage work — single quote with no servicable rates returns a 500

Unlike the findByIdOrFail issue, this one is in this package and could be fixed here. Recording it rather than folding a behaviour change into a coverage PR.

What

Api\v1\ServiceQuoteController::query() ends its service-rate branch with:

if ($single) {
    $bestQuote = $this->bestQuote($serviceQuotes);

    return $this->serviceQuoteResource($bestQuote);
}

bestQuote() is collect($serviceQuotes)->sortBy('amount')->first() — it returns null for an empty collection. serviceQuoteResource() is typed serviceQuoteResource(ServiceQuote $serviceQuote), non-nullable.

Effect

Requesting single=1 when no service rate is servicable for the given waypoints raises:

TypeError: serviceQuoteResource(): Argument #1 ($serviceQuote) must be of type
Fleetbase\FleetOps\Models\ServiceQuote, null given

That surfaces as an HTTP 500 rather than a meaningful "no quotes available" response. Hit while building a fixture with two company service rates that were not servicable for the payload's waypoints — a realistic configuration, not a contrived one.

The same shape appears twice in the file (the equivalent block around line 155 and again around line 329), so both entry points are affected.

Suggested fix

Return an explicit empty-quote response instead of passing null through:

if ($single) {
    $bestQuote = $this->bestQuote($serviceQuotes);

    if (!$bestQuote instanceof ServiceQuote) {
        return response()->apiError('No service quotes available for this route.', 404);
    }

    return $this->serviceQuoteResource($bestQuote);
}

Coverage note

The four lines in the second block (ServiceQuoteController 287, 297, 329, 331) remain uncovered. Reaching them needs a fixture where company service rates are both servicable for the waypoints and quotable end to end; the attempt for this PR produced quotes only through the earlier, already-covered block.