Troubleshooting

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:

# 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:

# 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:

# 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:

<testsuites>
    <testsuite name="Tests">
        <directory suffix="Test.php">./tests</directory>
    </testsuite>
</testsuites>

2. Verify test file naming:

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

3. Check test directory exists:

ls -la tests/

Wrong PHPUnit Version

Problem: PHPUnit schema errors or deprecated features

Solution:

Check PHPUnit version matches configuration:

vendor/bin/phpunit --version

Update phpunit.xml schema:

<!-- 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:

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

Or generate a new one:

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:

<php>
    <ini name="memory_limit" value="512M"/>
</php>

2. Run with more memory:

php -d memory_limit=512M vendor/bin/phpunit

3. Use process isolation:

<phpunit processIsolation="true">

Tests Timeout

Problem: Tests hang or timeout

Solutions:

1. Increase max execution time:

<php>
    <ini name="max_execution_time" value="300"/>
</php>

2. Check for infinite loops:

// Add timeouts to potentially long operations
$films = Streams::entries('films')
    ->timeout(30)
    ->get();

3. Run with verbose output to identify hanging test:

vendor/bin/phpunit --verbose --debug

Permission Denied Errors

Problem: Permission denied when accessing test data

Solution:

# 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:

ls -la vendor/streams/testing/laravel/streams/

2. Check backup data:

ls -la vendor/streams/testing/laravel/streams.bak/

3. Manually restore data:

public function setUp(): void
{
    parent::setUp();
    
    $this->restoreStreamsData();
}

4. Verify stream files are valid JSON:

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:

protected function tearDown(): void
{
    // Your cleanup code here
    
    parent::tearDown(); // Must call this!
}

2. Check file permissions:

# Ensure test can write and delete
chmod -R 755 vendor/streams/testing/laravel/streams

3. Manually verify restoration:

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:

# 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:

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);
}

2. Use verbose assertions:

$this->assertEquals(
    $expected,
    $actual,
    "Expected $expected but got $actual"
);

3. Run single test:

vendor/bin/phpunit --filter test_specific_method --testdox

Type Comparison Issues

Problem: Expected integer but got string

Solution:

Use appropriate assertions:

// 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:

// 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:

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

Config Not Loading

Problem: Configuration values not available

Solution:

Define config in TestCase:

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

Service Provider Not Loaded

Problem: Services not registered

Solution:

Register providers explicitly:

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:

{
    "phpunit.phpunit": "vendor/bin/phpunit",
    "phpunit.args": ["--colors=always"]
}

3. Reload window:
   • Cmd/Ctrl + Shift + P → Reload Window

Performance Issues

Tests Running Slowly

Solutions:

1. Use process isolation sparingly:

<!-- Only when needed -->
<phpunit processIsolation="false">

2. Disable coverage when not needed:

vendor/bin/phpunit --no-coverage

3. Run tests in parallel:

composer require --dev brianium/paratest
vendor/bin/paratest

4. Use SQLite in-memory for database tests:

<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>

High Memory Usage

Solutions:

1. Clear data after tests:

protected function tearDown(): void
{
    $this->clearData();
    parent::tearDown();
}

2. Use fewer fixtures:

// Load only needed data
$this->loadFixtures(['films']); // Not all streams

3. Garbage collection:

protected function tearDown(): void
{
    gc_collect_cycles();
    parent::tearDown();
}

Getting Help

Diagnostic Information

When reporting issues, include:

# 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:

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

Community Resources

• Documentation: https://streams.dev/docs/testing/introduction
• GitHub Issues: https://github.com/laravel-streams/streams-testing/issues
• Discord: Join the Streams community
• Stack Overflow: Tag with laravel-streams

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.