Assumptions Laravel Package

Getting Started

Install the package via Composer for test-time use:

composer require --dev mehr-als-nix/assumptions

Once installed, import the helper functions in your test files or base test case class. The package provides convenient static methods like assumeTrue(), assumeFalse(), assumeExtensionLoaded(), assumePhpVersion(), and assumeOperatingSystem() — all built on top of Hamcrest matchers. Begin by replacing @requires-annotated tests with inline assumption calls for better IDE support and more dynamic logic:

use function mehr\als\nix\assumptions\assumeExtensionLoaded;
use function mehr\als\nix\assumptions\assumePhpVersion;

class MyFeatureTest extends TestCase
{
    public function testWithPcntlSupport()
    {
        assumeExtensionLoaded('pcntl');
        // Proceed only if pcntl is available
        $this->assertTrue(function_exists('pcntl_fork'));
    }

    public function testOnlyOnLinux()
    {
        assumeOperatingSystem(OS_LINUX);
        // Rest of test logic...
    }
}

The package also includes a custom ResultPrinter to make skipped tests more descriptive—configure it in phpunit.xml (see wiki).

Implementation Patterns

• Base TestCase for Team-wide Assumptions: Create a TestCase base class and expose assumptions globally via use function declarations or static proxies. This ensures consistency and avoids use repetition.

• Pre-test Guard Hooks: Use assumptions inside @before or @beforeClass methods to skip entire test classes when system conditions (e.g., extension, PHP version, OS) are unmet. A failing assumption in a @beforeClass propagates to all tests in the class.

• Conditional Test Factories: Write data providers that rely on assumptions to skip irrelevant data sets dynamically—e.g., skip large datasets when memory is insufficient.

• Complement @requires: Use assumptions for runtime-evaluated checks where @requires only supports compile-time annotations (e.g., environment variables, dynamic paths, or custom conditions). For example:

  assumeThat($this->config->hasApiKey(), 'API key must be set');
  

• Custom Matchers: Extend Hamcrest matchers for domain-specific assumptions (e.g., assumeThat($db->status(), is('healthy'))) and bundle them into reusable helper functions.

Gotchas and Tips

• Skipped ≠ Passed: Tests with failing assumptions show as skipped, not passed. Verify your test runner (e.g., CI) interprets skip counts meaningfully—some tools flag skipped tests as failures unless explicitly configured.

• No Autoloading by Default: Unlike annotations, assumptions don’t auto-skip before class loading. Make sure the assume* functions are loaded early—include the helper file or rely on Composer’s autoloading (the package registers helpers via mehr-als-nix/assumptions/src/functions.php).

• PHPStan/Psalm Caution: Static analysis tools may not recognize dynamically imported functions like assumeExtensionLoaded(). Add @phpstan-import-return or define stubs to avoid errors.

• Limited Maintenance: The package hasn’t seen updates since 2018. While stable for PHPUnit ≤ 9, avoid relying on it for PHPUnit ≥ 10 (no official compatibility confirmed). Check if PHPUnit’s native require assertions or custom setUp() guards have caught up.

• IDE Support: Ensure your editor loads the function stubs (usually via functions.php). IDEs like PhpStorm may auto-detect them if Composer’s autoloading is configured, but explicit @method annotations or stub files improve autocomplete reliability.

• Hamcrest Integration: All assumptions use Hamcrest matchers under the hood (hamcrest/hamcrest-php). Leverage this for more expressive assertions:

  use Hamcrest\Matchers as H;
  
  assumeThat($value, H::greaterThan(10));
  

• ResultPrinter Enhancement: Enable the provided AssumptionResultPrinter in phpunit.xml for clearer console output showing why a test was skipped:

  <phpunit>
    <extensions>
      <extension class="mehr\als\nix\assumptions\ResultPrinter"/>
    </extensions>
  </phpunit>