orchestra / testbench-browser-kit
Laravel Browser Kit Testing Helper for Packages Development
Installs: 285 234
Dependents: 281
Suggesters: 1
Security: 0
Stars: 35
Watchers: 4
Forks: 3
Open Issues: 0
Requires
- php: ^8.2
- laravel/browser-kit-testing: ^7.2
- orchestra/testbench: ^9.5
- symfony/dom-crawler: ^7.0
Requires (Dev)
- laravel/pint: ^1.17
- phpstan/phpstan: ^1.11
- 9.x-dev
- v9.1.0
- v9.0.0
- 8.x-dev
- v8.6.0
- v8.5.0
- v8.4.0
- v8.3.0
- v8.2.0
- v8.1.0
- v8.0.1
- v8.0.0
- 7.x-dev
- v7.15.0
- v7.14.0
- v7.13.0
- v7.12.0
- v7.11.0
- v7.10.0
- v7.9.0
- v7.8.0
- v7.7.0
- v7.6.1
- v7.6.0
- v7.5.0
- v7.4.0
- v7.3.4
- v7.3.3
- v7.3.2
- v7.3.1
- v7.3.0
- v7.2.0
- v7.1.0
- v7.0.0
- 6.x-dev
- v6.20.0
- v6.19.0
- v6.18.0
- v6.17.3
- v6.17.2
- v6.17.1
- v6.17.0
- v6.16.1
- v6.16.0
- v6.15.0
- v6.14.0
- v6.13.0
- v6.12.0
- v6.11.0
- v6.10.0
- v6.9.0
- v6.8.0
- v6.7.0
- v6.6.0
- v6.5.1
- v6.5.0
- v6.4.0
- v6.3.0
- v6.2.0
- v6.1.0
- v6.0.0
- 5.x-dev
- v5.11.0
- v5.10.0
- v5.9.0
- v5.8.0
- v5.7.0
- v5.6.0
- v5.5.0
- v5.4.0
- v5.3.0
- v5.2.0
- v5.1.0
- v5.0.2
- v5.0.1
- v5.0.0
- 4.x-dev
- v4.15.0
- v4.14.0
- v4.13.0
- v4.12.0
- v4.11.0
- v4.10.0
- v4.9.0
- v4.8.0
- v4.7.0
- v4.6.0
- v4.5.0
- v4.4.1
- v4.4.0
- v4.3.0
- v4.2.0
- v4.1.0
- v4.0.1
- v4.0.0
- 3.9.x-dev
- v3.9.3
- v3.9.2
- v3.9.1
- v3.9.0
- 3.8.x-dev
- v3.8.0
- 3.7.x-dev
- v3.7.2
- v3.7.1
- v3.7.0
- 3.6.x-dev
- v3.6.1
- v3.6.0
- 3.5.x-dev
- v3.5.5
- v3.5.4
- v3.5.3
- v3.5.2
- v3.5.1
- v3.5.0
- 3.4.x-dev
- v3.4.1
- v3.4.0
- 3.3.x-dev
- v3.3.0
- 3.2.x-dev
- v3.2.0
- 3.1.x-dev
- v3.1.0
This package is auto-updated.
Last update: 2024-11-08 02:27:39 UTC
README
BrowserKit Testbench Component is a simple package that is supposed to help you write tests for your Laravel package using laravel/browser-kit-testing.
Version Compatibility
Installation
To install through composer, run the following command from terminal:
composer require --dev "orchestra/testbench-browser-kit"
Usages
Testbench Browser Kit added Browser Kit testing support for Laravel 5.4 and above. All you need to do is to replace Orchestra\Testbench\TestCase
to Orchestra\Testbench\BrowserKit\TestCase
and you should be good to go.
<?php namespace Tests; use Orchestra\Testbench\BrowserKit\TestCase as BaseTestCase; abstract class TestCase extends BaseTestCase { public $baseUrl = 'http://localhost'; // ... }
Introduction
Laravel BrowserKit Testing provides a very fluent API for making HTTP requests to your application, examining the output, and even filling out forms. For example, take a look at the test defined below:
<?php use Illuminate\Foundation\Testing\WithoutMiddleware; use Illuminate\Foundation\Testing\DatabaseTransactions; class ExampleTest extends TestCase { /** * A basic functional test example. * * @return void */ public function testBasicExample() { $this->visit('/') ->see('Laravel') ->dontSee('Rails'); } }
The visit
method makes a GET
request into the application. The see
method asserts that we should see the given text in the response returned by the application. The dontSee
method asserts that the given text is not returned in the application response. This is the most basic application test available in Laravel.
You may also use the 'visitRoute' method to make a 'GET' request via a named route:
$this->visitRoute('profile'); $this->visitRoute('profile', ['user' => 1]);
Interacting With Your Application
Of course, you can do much more than simply assert that text appears in a given response. Let's take a look at some examples of clicking links and filling out forms:
Interacting With Links
In this test, we will make a request to the application, "click" a link in the returned response, and then assert that we landed on a given URI. For example, let's assume there is a link in our response that has a text value of "About Us":
<a href="/about-us">About Us</a>
Now, let's write a test that clicks the link and asserts the user lands on the correct page:
public function testBasicExample() { $this->visit('/') ->click('About Us') ->seePageIs('/about-us'); }
You may also check that the user has arrived at the correct named route using the seeRouteIs
method:
->seeRouteIs('profile', ['user' => 1]);
Interacting With Forms
Laravel also provides several methods for testing forms. The type
, select
, check
, attach
, and press
methods allow you to interact with all of your form's inputs. For example, let's imagine this form exists on the application's registration page:
<form action="/register" method="POST"> {{ csrf_field() }} <div> Name: <input type="text" name="name"> </div> <div> <input type="checkbox" value="yes" name="terms"> Accept Terms </div> <div> <input type="submit" value="Register"> </div> </form>
We can write a test to complete this form and inspect the result:
public function testNewUserRegistration() { $this->visit('/register') ->type('Taylor', 'name') ->check('terms') ->press('Register') ->seePageIs('/dashboard'); }
Of course, if your form contains other inputs such as radio buttons or drop-down boxes, you may easily fill out those types of fields as well. Here is a list of each form manipulation method:
File Inputs
If your form contains file
inputs, you may attach files to the form using the attach
method:
public function testPhotoCanBeUploaded() { $this->visit('/upload') ->attach($pathToFile, 'photo') ->press('Upload') ->see('Upload Successful!'); }
Testing JSON APIs
Laravel also provides several helpers for testing JSON APIs and their responses. For example, the json
, get
, post
, put
, patch
, and delete
methods may be used to issue requests with various HTTP verbs. You may also easily pass data and headers to these methods. To get started, let's write a test to make a POST
request to /user
and assert that the expected data was returned:
<?php class ExampleTest extends TestCase { /** * A basic functional test example. * * @return void */ public function testBasicExample() { $this->json('POST', '/user', ['name' => 'Sally']) ->seeJson([ 'created' => true, ]); } }
{tip} The
seeJson
method converts the given array into JSON, and then verifies that the JSON fragment occurs anywhere within the entire JSON response returned by the application. So, if there are other properties in the JSON response, this test will still pass as long as the given fragment is present.
Verifying Exact Match
If you would like to verify that the given array is an exact match for the JSON returned by the application, you should use the seeJsonEquals
method:
<?php class ExampleTest extends TestCase { /** * A basic functional test example. * * @return void */ public function testBasicExample() { $this->json('POST', '/user', ['name' => 'Sally']) ->seeJsonEquals([ 'created' => true, ]); } }
Verifying Structural Match
It is also possible to verify that a JSON response adheres to a specific structure. In this scenario, you should use the seeJsonStructure
method and pass it your expected JSON structure:
<?php class ExampleTest extends TestCase { /** * A basic functional test example. * * @return void */ public function testBasicExample() { $this->get('/user/1') ->seeJsonStructure([ 'name', 'pet' => [ 'name', 'age', ], ]); } }
The above example illustrates an expectation of receiving a name
attribute and a nested pet
object with its own name
and age
attributes. seeJsonStructure
will not fail if additional keys are present in the response. For example, the test would still pass if the pet
had a weight
attribute.
You may use the *
to assert that the returned JSON structure has a list where each list item contains at least the attributes found in the set of values:
<?php class ExampleTest extends TestCase { /** * A basic functional test example. * * @return void */ public function testBasicExample() { // Assert that each user in the list has at least an id, name and email attribute. $this->get('/users') ->seeJsonStructure([ '*' => [ 'id', 'name', 'email', ], ]); } }
You may also nest the *
notation. In this case, we will assert that each user in the JSON response contains a given set of attributes and that each pet on each user also contains a given set of attributes:
$this->get('/users') ->seeJsonStructure([ '*' => [ 'id', 'name', 'email', 'pets' => [ '*' => [ 'name', 'age', ], ], ], ]);
Sessions / Authentication
Laravel provides several helpers for working with the session during testing. First, you may set the session data to a given array using the withSession
method. This is useful for loading the session with data before issuing a request to your application:
<?php class ExampleTest extends TestCase { public function testApplication() { $this->withSession(['foo' => 'bar']) ->visit('/'); } }
Of course, one common use of the session is for maintaining state for the authenticated user. The actingAs
helper method provides a simple way to authenticate a given user as the current user. For example, we may use a model factory to generate and authenticate a user:
<?php class ExampleTest extends TestCase { public function testApplication() { $user = factory(App\User::class)->create(); $this->actingAs($user) ->withSession(['foo' => 'bar']) ->visit('/') ->see('Hello, '.$user->name); } }
You may also specify which guard should be used to authenticate the given user by passing the guard name as the second argument to the actingAs
method:
$this->actingAs($user, 'api')
Disabling Middleware
When testing your application, you may find it convenient to disable middleware for some of your tests. This will allow you to test your routes and controller in isolation from any middleware concerns. Laravel includes a simple WithoutMiddleware
trait that you can use to automatically disable all middleware for the test class:
<?php use Illuminate\Foundation\Testing\WithoutMiddleware; use Illuminate\Foundation\Testing\DatabaseMigrations; use Illuminate\Foundation\Testing\DatabaseTransactions; class ExampleTest extends TestCase { use WithoutMiddleware; // }
If you would like to only disable middleware for a few test methods, you may call the withoutMiddleware
method from within the test methods:
<?php class ExampleTest extends TestCase { /** * A basic functional test example. * * @return void */ public function testBasicExample() { $this->withoutMiddleware(); $this->visit('/') ->see('Laravel'); } }
Custom HTTP Requests
If you would like to make a custom HTTP request into your application and get the full Illuminate\Http\Response
object, you may use the call
method:
public function testApplication() { $response = $this->call('GET', '/'); $this->assertEquals(200, $response->status()); }
If you are making POST
, PUT
, or PATCH
requests you may pass an array of input data with the request. Of course, this data will be available in your routes and controller via the Request instance:
$response = $this->call('POST', '/user', ['name' => 'Taylor']);
PHPUnit Assertions
Laravel provides a variety of custom assertion methods for PHPUnit tests: