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.48%	33,949 / 34,125 statements
Methods	97.12%	4,222 / 4,347 methods
Classes	82.15%	428 / 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.48%, 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.
• Fifteen production bugs found and fixed. Highlights:
  • Place::insertFromMixed() called insertFromGeocodingLookup() for any plain address string, but no such method existed on Place or any ancestor — every such call raised BadMethodCallException. Defined it as the insert-side twin of createFromGeocodingLookup, mirroring the existing insertFromGoogleAddress shape (the already-present but callerless getValuesFromGeocodingLookup() is exactly its other half).
  • 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 is 176 statements across 84 files, and it is very flat: 34 files have exactly one uncovered line, 30 have two, 13 have three. Per-file targeting stopped paying a while ago; the productive method at this density is profiling the uncovered lines for repeated shapes and writing one data-driven test per shape, plus classifying each line as reachable or unreachable before investing in a fixture.
• Recent sweeps: guard-clause bailouts across metrics/telematics providers/models, internal-only uuid resolution in relation filters, conditional requirement branches in place requests, uniqueness-rule scoping closures, relation-resource fallbacks for non-model resources, one-line delegation seams on controllers and commands, empty-input guards on multi-value filters, permission gating for global search, and service-area centre/centroid geometry.
• Surfaces previously written off as blocked that turned out to be reachable: the queryWithRequest seam on all 19 API controllers, Lalamove response handling (Guzzle client is an injectable property), Support\Auth::can() and the form requests gating on it (a real spatie fixture works), and every GEOS-dependent geometry accessor (inject a Brick\Geo\Engine\GeometryEngineRegistry fake — no native extension needed). Blocked labels are worth re-probing rather than trusting.
• The classification pass is as valuable as the tests: it repeatedly showed that a line I had queued as reachable was in fact unreachable, saving the fixture build. Roughly 40 lines are now confirmed dead by direct analysis.

Test-quality findings

Coverage percentage is not the same as verification, and two things found while working on this PR are worth stating plainly rather than leaving implied:

• OrderControllerNearbyFiltersTest registered its spatial functions as constants — ST_X always returned 103.8, ST_Distance_Sphere always 100.0 — so the distance filter those tests appear to exercise was never evaluated. They now decode the packed point and compute haversine on MySQL's earth radius, which verifies selection semantics (which rows fall inside the radius) though still not MySQL's exact arithmetic.
• Two defects remain in that same file, reported rather than fixed: its assertions use ->toBeGreaterThanOrEqual(0) on a count, which can never fail; and cross-test connection isolation leaks, so the controller can return rows seeded by a previous test. A test added there passed in isolation and failed in-file for exactly that reason, and was withdrawn rather than shipped green-by-ordering.

More broadly: this suite runs on in-memory SQLite with eval'd function shims, container stand-ins and hand-registered spatial UDFs. It is good at proving branch logic and contracts, and poor at proving anything about real MySQL behaviour — the spatial write paths especially, where a fixture's prepareBindings override compensates for a real cast divergence. Treat a green run as "the branches behave as described", not "the feature works against a real database".

Validation

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

• php -l <changed test file>
• php scripts/pest-runner.php <changed test file> — pass count compared against the declared test( count, since a fatal truncates a run without reporting any failure
• XDEBUG_MODE=coverage php scripts/coverage-file-runner.php --coverage-clover=... <changed test file> — per-line slice check that the intended lines actually executed, before trusting a green assertion
• vendor/bin/php-cs-fixer fix --using-cache=no <changed file>
• composer test:lint
• PATH=<asdf php 8.4 bin>:$PATH XDEBUG_MODE=coverage 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	11
server/src/Http/Controllers/Internal/v1/OrderController.php	7
server/src/Models/Place.php	7
server/src/Http/Controllers/Api/v1/DriverController.php	5
server/src/Models/Payload.php	5

These files are now majority-dead rather than untested: 5 of the 7 remaining in Models/Place.php, 2 of the 5 in Api/v1/DriverController.php, and 2 of the 5 in Models/Payload.php are confirmed unreachable (see below).

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 one arm above
Models/Place::findExistingSharedPlace	$location is initialised to a SpatialPoint and the catch assigns one, so the non-point guard cannot fire
Models/Place::insertFromMixed (address key)	the guard sits in the is_string($place) branch, and empty() on a non-numeric string offset is always true, so it never fires
Models/Place::insertFromMixed (GoogleAddress arm)	shadowed by an earlier is_array($place) || is_object($place) arm that catches every object first
Http/Controllers/Api/v1/OrderController::updateActivity	the if (!$order) guard follows a try/catch whose findOrder() is : Order-typed and throws rather than returning null
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
Http/Controllers/Internal/v1/OrderController::statuses	guards method_exists($config, 'activities'), but OrderConfig::activities() is declared
Http/Controllers/Internal/v1/TelematicController::testCredentials	guards registry->resolve(), typed : TelematicProviderInterface, which throws rather than returning null (the surrounding try/catch reports it)
Models/ServiceArea::createMultiPolygonFromPoint	duplicates the ring-closing guard; Utils::coordsToCircle() already returns a closed ring, so first !== last is never true
Http/Resources/v1/{PurchaseRate,TrackingStatus} relation accessors	the middle branch is guarded by method_exists($this, 'loadMissing'), but no class in the hierarchy (FleetbaseResource -> JsonResource) declares it — it only resolves via __call, which method_exists does not see
Models/Payload::setPlace	Place::createFromMixed(): ?Place always yields a Model or null, so the Str::isUuid() arm and the trailing else are both shadowed by the instanceof Model arm between them
Models/ServiceRate::getLngLatFromPlace	guards Place::getLocationAsPoint(), declared : SpatialPoint (non-nullable), and a SpatialPoint always exposes getLat/getLng
Exports/VehicleExport::locationPart	guards Utils::castPoint(), which catches every failure and falls back to Point(0, 0), so it is never falsy
Models/Place::insertFromMixed / createFromMixed	see the two entries above plus the shadowed-arm rows — 5 of this file's 7 remaining lines are unreachable

Three 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;
• 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;
• Support\Auth::can() and the form requests that gate on it — a real spatie fixture works (permissions seeded with guard sanctum, plus model_has_permissions rows keyed to the session user's CompanyUser uuid). The internal create-driver and create-order-config requests now resolve opposite ways through that one gate, which proves the permission is genuinely consulted rather than blanket-true.

The lesson is to re-probe "blocked" labels periodically rather than trusting them.

Two further lines (Internal/v1/OrderController 887-888) are reachable only once the upstream findByIdOrFail defect below 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.

Known in-package defect (deferred, not fixed here)

Api\v1\ServiceQuoteController::bestQuote() returns null for an empty collection and is passed straight into serviceQuoteResource(ServiceQuote $serviceQuote), which is non-nullable — so requesting single=1 when no service rate is servicable for the given waypoints returns HTTP 500 instead of a meaningful "no quotes available" response. The same shape appears at two entry points in that file. Details and a suggested guard are in this PR comment. Left unfixed deliberately: it is a behavior change that does not belong in a coverage PR.

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.
• Slice-level coverage is verified per change: a passing assertion does not by itself prove the targeted lines executed, so each new test is checked line-by-line against a Clover slice before it is committed.

[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 ☂️