How a static icon test prevented production crashes in Laravel UI

A recent bug hunt in the Laravel admin UI of the laravel-config-sso package revealed a frustrating pattern: the issue slipped past every feature test, only to surface in production. The root cause wasn’t a complex logic flaw—it was a simple icon name mismatch. Despite extensive test coverage, the bug remained invisible until the full application environment was engaged. This experience underscored a critical gap in testing strategies: certain classes of bugs only reveal themselves in runtime, where automated tests fail to replicate the production-like conditions.

The hidden danger of icon resolution failures

The admin interface relied on Flux, a Livewire-based UI library that resolves icons through a specific naming convention. Unlike Lucide’s familiar syntax, Flux expects Heroicons, leading to subtle yet critical discrepancies. For example, developers accustomed to typing ellipsis for a three-dot menu icon might unknowingly use a Lucide name in Flux, which expects ellipsis-horizontal. When Flux encounters an unrecognized icon, it throws a runtime error—one that doesn’t occur in headless test environments.

In the affected package, a feature test confirmed that the admin route returned a 200 status code, masking the underlying issue. The error only emerged when the application was fully booted, a scenario automated tests rarely simulate. This disconnect between testing and production environments creates a blind spot where bugs thrive, waiting to ambush users.

Why dynamic tests fall short for static assets

Most feature and unit tests evaluate application behavior by simulating user interactions or verifying API responses. However, these tests often overlook static assets like Blade templates, where icon references reside. In headless test environments, Flux’s icon resolution mechanism behaves as a no-op—it doesn’t actually render icons, so invalid names go undetected.

This behavior mirrors the limitations of a spell-checker that only runs when a document is printed, not while it’s being written. Developers receive no feedback during testing, and the error only surfaces when the application is deployed to a live environment. The result is a false sense of security, where tests pass but the application fails in production.

Building a static test to validate Flux icons

To bridge this gap, a targeted test was developed to scan the Blade template for icon references and validate them against Flux’s icon registry. The test reads the template file, extracts static icon names (e.g., icon="eye-off"), and parses dynamic expressions (e.g., icon="{{ $cond ? 'eye-slash' : 'eye' }}"). It then checks each icon name against the actual icons available in Flux’s stub directory.

$fluxIconStubs = base_path('vendor/livewire/flux/stubs/resources/views/flux/icon');
it('only references Flux icons that exist', function () use ($fluxIconStubs) {
    expect(is_dir($fluxIconStubs))->toBeTrue("Flux icon stubs not found");
    
    $view = file_get_contents(__DIR__.'/../../resources/views/livewire/sso-providers.blade.php');
    
    // Extract static and dynamic icon names
    preg_match_all('/icon="([a-z][a-z0-9-]*)"/', $view, $static);
    preg_match_all('/icon="\{\{(.+?)\}\}"/', $view, $dynamic);
    
    $names = $static[1];
    foreach ($dynamic[1] as $expression) {
        preg_match_all("/'([a-z][a-z0-9-]*)'"/, $expression, $tokens);
        $names = array_merge($names, $tokens[1]);
    }
    
    $names = array_values(array_unique($names));
    expect($names)->not->toBeEmpty();
    
    foreach ($names as $name) {
        expect(is_file("{$fluxIconStubs}/{$name}.blade.php"))
            ->toBeTrue("Flux has no icon [{$name}] — use a valid Heroicon name (Flux ships Heroicons, not Lucide).");
    }
});

This approach offers three key advantages:

• Direct validation against the source of truth: The test checks icon names against Flux’s actual stub files in the vendor directory, ensuring accuracy without relying on hardcoded lists that can become outdated.

• Support for dynamic icons: Regular expressions capture icon names embedded in Blade expressions, such as ternary operators or conditional logic, which are common sources of mismatches.

• Actionable failure messages: When a test fails, it explicitly states the issue—for example, highlighting that Flux uses Heroicons, not Lucide—and guides developers toward the correct naming convention.

The immediate payoff was significant. Later that same day, a similar bug surfaced in another package, this time involving icons like webhook, ellipsis, and list—all exclusive to Flux Pro. Without the static test, these issues would have evaded detection until production, potentially disrupting workflows for end users.

When static validation outperforms dynamic testing

Static tests like this one are invaluable in scenarios where runtime behavior differs from testing conditions. Common use cases include:

• Component rendering: Libraries that transform or mock components during testing may hide errors that only appear in a fully rendered environment.

• Environment-specific logic: Features that behave differently in development versus production, such as feature flags or environment-based configurations.

• Third-party integrations: Dependencies that simulate or stub functionality during tests but behave unpredictably in production.

The guiding principle is straightforward: if a bug only emerges when the application is fully operational but automated tests fail to replicate that state, consider supplementing dynamic tests with static validation. This strategy shifts failures from production to CI, where they can be addressed proactively and cost-effectively.

The lesson is clear: don’t let your test suite create a false sense of security. By integrating static checks that validate source assets, you can catch subtle yet critical issues before they reach users, ensuring a smoother and more reliable experience from development to deployment.