Tests Laravel Package

Getting Started

This package is not meant for end-user application development—it’s a dedicated test suite for the php-ds extension itself. As a developer, you’ll only interact with it if you’re:

• Contributing to php-ds (core extension or wrapper libraries)
• Maintaining or debugging the extension
• Validating compatibility before upgrading PHP versions

To begin:

1. Clone the php-ds extension repo (e.g., https://github.com/php-ds/ext-ds) and ensure the php-ds extension is enabled in your php.ini.
2. Clone php-ds/tests and run tests via PHPUnit:

   composer install
   ./vendor/bin/phpunit
   

3. Start with tests/Vector/ or tests/Map/ to understand how core structures are validated—these are the most frequently used.

Implementation Patterns

Since this is a test suite—not a library—integration isn’t about "using it in your app." Instead, adopt these patterns when developing alongside php-ds:

• As a contributor:

  • Add new tests in tests/{Structure}/ to cover bug fixes, edge cases, or new methods.
  • Follow existing naming conventions (e.g., Vector/emptyTest.php, Map/mergeTest.php).
  • Use data providers for parametrized tests (e.g., testing with null, arrays, scalar types).

• As a maintainer:

  • Hook tests into CI (GitHub Actions, GitLab CI) with matrix builds across PHP versions (7.4–8.3+).
  • Use --group filters to run only relevant tests during development:

    ./vendor/bin/phpunit --group map
    

  • Audit failing tests as regression alerts—they often reveal subtle API drift (e.g., return type changes, memory safety issues).

• As a library author (e.g., building an ORM over php-ds):

  • Run this suite as part of your test suite’s CI to guarantee compatibility:

    git clone https://github.com/php-ds/tests.git ./vendor/php-ds-tests
    ./vendor/bin/phpunit ./vendor/php-ds-tests
    

Gotchas and Tips

• Misconception warning: This package does not ship with php-ds—you must clone it separately. It’s not installed via composer require.
• PHP version mismatches: Tests may fail on outdated php-ds versions if run against newer PHP. Always verify your php-ds extension version matches the test suite’s target (check tests/bootstrap.php or phpunit.xml).
• CI pitfalls: Avoid running tests with OPcache enabled—some tests mutate internal states in ways that trip cached bytecode. Use php -d opcache.enable=0.
• Debugging edge cases: For flaky tests (e.g., memory-related), use valgrind or phpdbg to detect memory leaks or undefined behavior.
• Extensibility: While tests are hardcoded, you can extend fixtures by creating tests/Custom/ with your own .test.php files and referencing them in phpunit.xml.
• Documentation value: Leverage passing tests as living spec—if a behavior is tested, it’s a contract; if untested, it’s implementation detail. Use this to justify API decisions in pull requests.