Weave Code
Assert Throws Laravel Package
codeception/assert-throws
Adds assertThrows-style assertions to Codeception, letting you easily verify exceptions in tests. Assert the exception type and optionally message/code when running a callable, making negative-path testing clearer and less verbose.
Assert exception handling without stopping a test. For PHPUnit 6+
Frequently asked questions about Assert Throws
- Can I use assertThrows in Laravel tests without Codeception?
- Yes, but with a small wrapper. The package is designed for Codeception, but you can create a helper like `assertThrowsException()` to replicate its behavior in PHPUnit. The core logic works with any callable that throws exceptions.
- How does assertThrows differ from PHPUnit’s expectException()?
- Unlike `expectException()`, which halts the test on failure, `assertThrows()` lets the test continue. This is useful for verifying exceptions in multi-step tests or when cleanup is needed after failure. It also supports optional message/code matching.
- Will this break my existing Laravel 8+ tests if I add it?
- No, it’s a drop-in addition. The package doesn’t modify Laravel’s core or test suite—it only adds a new assertion method. Run `composer require --dev codeception/assert-throws` and update your test files incrementally.
- Can I test Laravel-specific exceptions like ValidationException or HttpResponseException?
- Absolutely. The package treats exceptions as generic PHP objects, so you can assert any exception type, including Laravel’s built-in ones. For example: `$this->assertThrows(ValidationException::class, fn() => $validator->validate($data));`
- Does assertThrows work with Laravel’s HTTP tests (e.g., testing API error responses)?
- Yes, it’s perfect for HTTP tests. Use it to verify exceptions thrown by routes or controllers, like unauthorized access or invalid payloads. Example: `$this->assertThrows(UnauthorizedException::class, fn() => $this->get('/admin'));`
- How do I migrate from try-catch blocks to assertThrows in my Laravel tests?
- Replace verbose try-catch logic with `assertThrows()`. For example, instead of catching `AuthorizationException` manually, use `$this->assertThrows(AuthorizationException::class, fn() => $this->call('GET', '/admin'));` to keep tests DRY and readable.
- Will this slow down my CI/CD pipeline?
- No, it’s lightweight. Since it doesn’t halt tests on failure (unlike `expectException()`), your pipeline may run slightly faster. However, test duration depends on your callable’s execution time, not the assertion itself.
- Are there alternatives to assertThrows for Laravel exception testing?
- Yes, but they’re less flexible. PHPUnit’s `expectException()` halts tests, and custom try-catch blocks are verbose. For Codeception users, `assertThrows` is the most concise and maintainable option. If you’re not using Codeception, consider `assertThat()` with PHPUnit’s exception matcher.
- How do I test exceptions with custom messages or codes in Laravel?
- Use the optional second and third parameters. For example: `$this->assertThrows(ValidationException::class, 'The email field is required.', 10001, fn() => $validator->validate(['email' => '']));` This ensures both type and details match.
- Does this package support Laravel’s testing helpers like $this->partialMock() or $this->assertDatabaseHas()?
- No, it’s focused solely on exception assertions. However, you can combine it with Laravel’s helpers. For example, mock a service, then use `assertThrows()` to verify exceptions in its methods: `$service = $this->partialMock(MyService::class); $this->assertThrows(ServiceException::class, fn() => $service->doSomething());`
Weaver
How can I help you explore Laravel packages today?