Pest Plugin Inside Laravel Package

Getting Started

Install the plugin via Composer:

composer require --dev faissaloux/pest-plugin-inside

No additional configuration is required—Pest auto-discovers it. Begin by replacing traditional expect() calls with inside() when testing object boundaries or domain contexts. For example:

use function Pest faissaloux\Inside\inside;

describe('User::fullName()', function () {
    $user = new User('John', 'Doe');

    it('returns the full name', function () {
        inside($user)->expect(fn () => $this->fullName())->toBe('John Doe');
    });
});

Start here if your tests have repeated setup for object state or you want to signal where an assertion is semantically anchored.

Implementation Patterns

• Domain-scoped assertions: Wrap expectations inside model instances, value objects, or service classes to make test intent explicit:

  inside($invoice)->expect(fn () => $this->total())->toBe(100.00);
  

• Factory-driven test contexts: Use with Pest factories to scope assertions to generated domain contexts:

  $user = UserFactory::new()->create();
  inside($user)->group('authentication', fn () => [
      expect($user->isActive())->toBeTrue(),
      expect($user->email())->toContain('@example.com'),
  ]);
  

• Nested contexts: Chain or nest inside() calls for layered boundaries (e.g., inside($repository)->inside($entity)) where each scope carries semantic meaning.
• Integration with Pest globals: Works alongside with(), in(), and see()—use inside() only for object-bound assertions to avoid overuse.

Gotchas and Tips

• Scope pollution: Avoid calling inside() on objects that mutate state mid-test. Ensure the object is fully constructed before passing it in.
• Closure signature matters: The closure passed to inside() executes in the object’s scope ($this → object instance). Conflicts arise if the object has __call() or dynamic methods—use ::class or get_class($this) to verify context.
• Debugging: Enable pest('inside')->shouldCallOriginal() to fallback to raw expectations if unexpected behavior occurs.
• Performance: Minimal overhead, but skip inside() for trivial scalar comparisons (e.g., expect($foo)->toBe(1)). Reserve it for domain complexity.
• Extension point: The plugin exposes InsideContext—subclass it to add custom domain helpers (e.g., inside($order)->assertProcessed()).