Net Mock Laravel Package

Product Decisions This Supports

• Testability & CI/CD Efficiency: Enables deterministic unit/integration testing for stream-based functionality (e.g., network clients, file I/O wrappers, or custom stream abstractions), reducing flaky test failures in CI pipelines by eliminating dependency on real I/O.
• Build vs. Buy: Buy—avoids reinventing mocking logic for phrity/net-stream while maintaining 1:1 compatibility with the real implementation. Justifies investment if the team uses or plans to adopt phrity/net-stream for networking, file handling, or custom stream abstractions.
• Feature Roadmap:
  • Networking/IO-heavy features: Critical for testing components like HTTP clients, WebSocket handlers, or custom protocols built on streams.
  • Debugging/Observability: Log stream interactions via PSR-3 loggers (e.g., Monolog) to diagnose issues in staging/production.
  • Mock-driven development: Accelerate TDD for stream-dependent logic (e.g., "verify a socket writes exactly 3 times before closing").
• Use Cases:
  • Legacy System Modernization: Mock external dependencies (e.g., legacy TCP services) to refactor without breaking changes.
  • Edge-Case Testing: Simulate malformed streams, timeouts, or partial reads/writes without real hardware.
  • Performance Testing: Mock slow streams to test timeouts, retries, or backpressure handling.
  • Laravel-Specific: Test queue workers, HTTP clients (Guzzle/Pest), or custom stream-based services (e.g., file uploads, WebSockets).

When to Consider This Package

• Adopt if:
  • Your Laravel app uses phrity/net-stream (or plans to) for stream operations (sockets, pipes, custom streams).
  • You need deterministic tests for stream interactions to eliminate flaky CI failures.
  • Your team prioritizes mock-driven development over real I/O in tests.
  • You require fine-grained control over stream behavior (e.g., injecting errors, delaying responses, or asserting call sequences).
  • You’re testing Laravel-specific components that rely on streams (e.g., queue workers, HTTP clients, or custom services).
• Look elsewhere if:
  • You’re not using phrity/net-stream—this package is tightly coupled to its API. Use native PHP mocks or Pest’s HTTP testing instead.
  • Your tests require real I/O (e.g., testing actual network protocols). Use VCR for HTTP or Pest’s HTTP client for API testing.
  • You need mocking for other PHP stream abstractions (e.g., ReactPHP, Guzzle). Consider Mockery or PHPUnit’s built-in mocks.
  • Your team lacks PHPUnit experience—this package’s expectation stack requires familiarity with trait-based testing.
  • You’re on PHP <8.1 or Laravel <8.0, as the package requires PHP 8.1+.

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us write reliable, fast tests for stream-based features—critical for our [networking/IO-heavy product, e.g., real-time APIs, file processing, or WebSocket services]. By mocking phrity/net-stream, we’ll:

• Eliminate flaky CI tests (no more failures due to network variability or external dependencies).
• Accelerate development by testing edge cases (e.g., timeouts, malformed data) without real hardware.
• Reduce costs by avoiding custom mocking logic (MIT-licensed, no vendor lock-in). Ask: Should we prioritize this for [Q3 roadmap] to unblock [specific feature, e.g., ‘WebSocket scalability tests’ or ‘file upload validation’]?"

For Engineers:

*"This is a drop-in mocking layer for phrity/net-stream that:

• Replaces real streams with testable stubs (e.g., verify a socket writes hello before closing).
• Logs all interactions (debug issues via PSR-3 loggers like Monolog).
• Works seamlessly with Laravel (bind to service container, toggle in tests). Why it’s better than alternatives:
• No flaky tests: Unlike real I/O, mocks are deterministic and fast.
• Zero refactoring: Swap RealStreamFactory ↔ MockStreamFactory in one line.
• Future-proof: Supports phrity/net-stream v1.0–v2.4+. Proposal: Use this for [specific component, e.g., ‘queue workers’ or ‘HTTP client retries’] to [goal: e.g., ‘ship feature X faster’ or ‘reduce CI noise’]."*

For QA/DevOps:

*"This solves our top CI pain point: stream-related tests failing due to network variability or external dependencies. With this:

• Tests run 10x faster (no real I/O).
• We can reproduce bugs by injecting specific stream errors (e.g., ‘simulate a 500ms delay’).
• Onboarding gets easier—new devs won’t hit ‘it works on my machine’ issues. Ask: Can we add this to our [test automation pipeline] for [module Y, e.g., ‘file upload service’]?"

For Laravel-Specific Teams:

*"This integrates natively with Laravel’s ecosystem:

• Service Container: Bind MockStreamFactory for tests, RealStreamFactory for production.
• Pest/PHPUnit: Use traits like ExpectSocketStreamTrait for clean assertions.
• Logging: Works with Laravel’s Monolog or default logger. Example: Test a queue worker that uses streams:

// config/testing.php
'streams' => [
    'factory' => \Phrity\Net\Mock\StreamFactory::class,
],

// Test
$this->expectSocketStreamWrite()->addAssert(fn ($method, $params) =>
    $this->assertEquals('data', $params[0])
);
$worker->process(); // Now deterministic!
```"