Skip to content

Troubleshooting

Partial

This feature is partially implemented. Check the documented limitations before using it.

Common issues when testing with Streams Testing.

This guide helps you resolve common issues when using the Streams Testing package.

Installation Issues

Class Not Found

Problem: Class 'Streams\Testing\TestCase' not found

Solution:

terminal
# Regenerate autoload files
composer dump-autoload

# Clear any cached autoload files
rm -rf vendor/composer
composer install

PHPUnit Not Found

Problem: vendor/bin/phpunit: No such file or directory

Solution:

terminal
# Reinstall dev dependencies
composer install --dev

# Or explicitly require PHPUnit
composer require --dev phpunit/phpunit

Orchestra Testbench Missing

Problem: Class 'Orchestra\Testbench\TestCase' not found

Solution:

terminal
# Install compatible version
composer require --dev orchestra/testbench:^8.0

Configuration Issues

No Tests Found

Problem: PHPUnit reports No tests executed!

Solutions:

  1. Check phpunit.xml test suite configuration:
example.xml
<testsuites>
    <testsuite name="Tests">
        <directory suffix="Test.php">./tests</directory>
    </testsuite>
</testsuites>

  1. Verify test file naming:

    • Files must end with Test.php (e.g., FilmTest.php)
    • Test methods must start with test or use @test annotation

  2. Check test directory exists:

terminal
ls -la tests/

Wrong PHPUnit Version

Problem: PHPUnit schema errors or deprecated features

Solution:

Check PHPUnit version matches configuration:

terminal
vendor/bin/phpunit --version

Update phpunit.xml schema:

example.xml
<!-- For PHPUnit 10 -->
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"

<!-- For PHPUnit 9 -->
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"

Missing APP_KEY

Problem: No application encryption key has been specified

Solution:

Add to phpunit.xml:

example.xml
<php>
    <env name="APP_KEY" value="base64:aiGINJ0oFnqrMGUwJYWJuhe6meZoW+GqppwDJD4YZeM="/>
</php>

Or generate a new one:

terminal
php artisan key:generate --show

Test Execution Issues

Memory Limit Exceeded

Problem: Fatal error: Allowed memory size exhausted

Solutions:

  1. Increase memory limit in phpunit.xml:
example.xml
<php>
    <ini name="memory_limit" value="512M"/>
</php>
  1. Run with more memory:
terminal
php -d memory_limit=512M vendor/bin/phpunit
  1. Use process isolation:
example.xml
<phpunit processIsolation="true">

Tests Timeout

Problem: Tests hang or timeout

Solutions:

  1. Increase max execution time:
example.xml
<php>
    <ini name="max_execution_time" value="300"/>
</php>
  1. Check for infinite loops:
example.php
// Add timeouts to potentially long operations
$films = Streams::entries('films')
    ->timeout(30)
    ->get();
  1. Run with verbose output to identify hanging test:
terminal
vendor/bin/phpunit --verbose --debug

Permission Denied Errors

Problem: Permission denied when accessing test data

Solution:

terminal
# Make streams directories writable
chmod -R 775 vendor/streams/testing/laravel/streams
chmod -R 775 vendor/streams/testing/laravel/streams.bak

# Or change ownership
sudo chown -R $USER:$USER vendor/streams/testing/laravel/streams

Test Data Issues

Test Data Not Loading

Problem: Sample streams return empty results

Solutions:

  1. Verify test data exists:
terminal
ls -la vendor/streams/testing/laravel/streams/
  1. Check backup data:
terminal
ls -la vendor/streams/testing/laravel/streams.bak/
  1. Manually restore data:
example.php
public function setUp(): void
{
    parent::setUp();
    
    $this->restoreStreamsData();
}
  1. Verify stream files are valid JSON:
terminal
php -r "json_decode(file_get_contents('vendor/streams/testing/laravel/streams/films.json'));"

Data Not Resetting Between Tests

Problem: Modified data persists across tests

Solutions:

  1. Ensure parent tearDown is called:
example.php
protected function tearDown(): void
{
    // Your cleanup code here
    
    parent::tearDown(); // Must call this!
}
  1. Check file permissions:
terminal
# Ensure test can write and delete
chmod -R 755 vendor/streams/testing/laravel/streams
  1. Manually verify restoration:
example.php
public function test_data_resets()
{
    $initialCount = Streams::entries('films')->count();
    
    Streams::make('films')->create(['title' => 'New Film']);
    
    $this->restoreStreamsData();
    
    $finalCount = Streams::entries('films')->count();
    $this->assertEquals($initialCount, $finalCount);
}

Invalid JSON in Stream Files

Problem: JSON decode error when loading streams

Solution:

Validate and fix JSON:

terminal
# Validate JSON
cat vendor/streams/testing/laravel/streams/films.json | python -m json.tool

# Or use jq
jq . vendor/streams/testing/laravel/streams/films.json

Assertion Issues

Unexpected Test Failures

Problem: Tests fail unexpectedly

Debug Steps:

  1. Add debug output:
example.php
public function test_debug_example()
{
    $films = Streams::entries('films')->get();
    
    dump($films->count()); // Check actual count
    dd($films->toArray()); // Inspect full data
    
    $this->assertCount(7, $films);
}
  1. Use verbose assertions:
example.php
$this->assertEquals(
    $expected,
    $actual,
    "Expected $expected but got $actual"
);
  1. Run single test:
terminal
vendor/bin/phpunit --filter test_specific_method --testdox

Type Comparison Issues

Problem: Expected integer but got string

Solution:

Use appropriate assertions:

example.php
// Loose comparison
$this->assertEquals(7, $count);

// Strict comparison
$this->assertSame(7, $count);

// Type checking
$this->assertIsInt($count);
$this->assertEquals(7, (int) $count);

Collection vs Array Confusion

Problem: Assertions fail on collections

Solution:

Convert collections appropriately:

example.php
// Get collection
$films = Streams::entries('films')->get();

// For counting
$this->assertCount(7, $films);

// For array assertions
$this->assertIsArray($films->toArray());

// For iteration
foreach ($films as $film) {
    $this->assertNotNull($film);
}

Laravel Integration Issues

Route Not Found in Tests

Problem: Route [name] not defined

Solution:

Ensure routes are loaded in TestCase:

example.php
protected function getPackageProviders($app)
{
    return [
        \Your\Package\ServiceProvider::class,
    ];
}

Config Not Loading

Problem: Configuration values not available

Solution:

Define config in TestCase:

example.php
protected function defineEnvironment($app)
{
    $app['config']->set('streams.path', __DIR__ . '/streams');
}

Service Provider Not Loaded

Problem: Services not registered

Solution:

Register providers explicitly:

example.php
protected function getPackageProviders($app)
{
    return [
        \Streams\Core\StreamsServiceProvider::class,
        \Streams\Testing\TestServiceProvider::class,
    ];
}

IDE Issues

PHPStorm Not Running Tests

Problem: Can't run tests from IDE

Solutions:

  1. Configure PHPUnit:

    • Settings → PHP → Test Frameworks
    • Add PHPUnit Local
    • Use Composer autoloader: vendor/autoload.php

  2. Mark directories:

    • Right-click tests/ → Mark Directory As → Test Sources Root

  3. Refresh configuration:

    • File → Invalidate Caches / Restart

VS Code Not Recognizing Tests

Problem: Test runner doesn't find tests

Solutions:

  1. Install PHPUnit extension:

    • Better PHPUnit by calebporzio

  2. Configure settings.json:

example.json
{
    "phpunit.phpunit": "vendor/bin/phpunit",
    "phpunit.args": ["--colors=always"]
}
  1. Reload window:
    • Cmd/Ctrl + Shift + P → Reload Window

Performance Issues

Tests Running Slowly

Solutions:

  1. Use process isolation sparingly:
example.xml
<!-- Only when needed -->
<phpunit processIsolation="false">
  1. Disable coverage when not needed:
terminal
vendor/bin/phpunit --no-coverage
  1. Run tests in parallel:
terminal
composer require --dev brianium/paratest
vendor/bin/paratest
  1. Use SQLite in-memory for database tests:
example.xml
<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>

High Memory Usage

Solutions:

  1. Clear data after tests:
example.php
protected function tearDown(): void
{
    $this->clearData();
    parent::tearDown();
}
  1. Use fewer fixtures:
example.php
// Load only needed data
$this->loadFixtures(['films']); // Not all streams
  1. Garbage collection:
example.php
protected function tearDown(): void
{
    gc_collect_cycles();
    parent::tearDown();
}

Getting Help

Diagnostic Information

When reporting issues, include:

terminal
# PHP version
php -v

# Composer info
composer show

# PHPUnit version
vendor/bin/phpunit --version

# Streams core version
composer show streams/core

# Run tests with verbose output
vendor/bin/phpunit --verbose --debug

Enable Debug Mode

Add to phpunit.xml:

example.xml
<php>
    <env name="APP_DEBUG" value="true"/>
    <ini name="display_errors" value="1"/>
    <ini name="error_reporting" value="E_ALL"/>
</php>

Community Resources

Quick Checklist

When tests aren't working, check:

  • composer dump-autoload executed
  • phpunit.xml exists and is valid
  • Test files end with Test.php
  • Test methods start with test
  • Extending \Streams\Testing\TestCase
  • parent::setUp() and parent::tearDown() called
  • File permissions correct on stream data
  • APP_KEY set in phpunit.xml
  • Correct PHP version (8.2+)
  • Dependencies installed with composer install

Still having issues? Check the GitHub issues or create a new one with the diagnostic information above.