Learn the API

If you'd like to dig into the API examples from above a bit more, here is what each method call accomplishes.

All Extensions

visit($uri)

This will perform a GET request to the given $uri, while also triggering an assertion to guarantee that a 200 status code was returned.

$this->visit('/page');

see($text)

To verify that the current page contains the given text, you'll want to use the see method.

$this->visit('/page')
     ->see('Hello World');

Tip: The word "and" may be prepended to any method call to help with readability. As such, if you wish, you may write: $this->visit('/page')->andSee('Hello World');.

To negate the assertion, you may use notSee.

click($linkText) or follow($linkText)

To simulate the behavior of clicking a link on the page, the click method is your friend.

$this->visit('/page')
     ->click('Follow Me');

While it's easiest if you pass the text content of the desired anchor tag to the click method (like "Sign Up"), you may also use the anchor tag's name or id attributes if you wish.

Behind the scenes, this package will determine that destination of the link (the "href"), and make a new "GET" request, accordingly. Alternatively, you may use the follow() method. Same thing.

seePageIs($uri) and onPage($uri)

In many situations, it can prove useful to make an assertion against the current url.

$this->visit('/page')
     ->click('Follow Me')
     ->seePageIs('/next-page');

Alternatively, if it offers better readability, you may use the onPage method instead. Both are equivalent in functionality. This is especially true when it follows a see assertion call.

$this->visit('/page')
     ->click('Follow Me')
     ->andSee('You are on the next page')
     ->onPage('/next-page');

To negate the assertion, you may use notSeePageIs.

type($text, $selector) or fill($text, $selector)

If you need to type something into an input field, one option is to use the type method, like so:

$this->visit('search')
     ->type('Total Recall', '#q');

Simply provide the value for the input, and a CSS selector for us to hunt down the input that you're looking for. You may pass an id, element name, or an input with the given "name" attribute. The fill method is an alias that does the same thing.

tick($name) or check($name)

To "tick" a checkbox, call the tick method, and pass either the id or the name of the input.

$this->visit('newsletter')
     ->tick('opt-in')
     ->press('Save');

The check method is an alias for tick. Use either.

select($selectName, $optionValue)

This method allows you to select an option from a dropdown. You only need to provide the name of the select element, and the value attribute from the desired option tag.

$this->visit('signup')
     ->select('plan', 'monthly')
     ->press('Sign Up');

The following HTML would satisfy the example above:

<form method="POST" action="...">
  <select name="plan">
    <option value="monthly">Monthly</option>
    <option value="yearly">Yearly</option>
  </select>

  <input type="submit" value="Sign Up">
</form>

attachFile($fileInputName, $absolutePath)

Imagine that, as part of filling out a form, you need to attach a file. Easy enough!

$this->visit('/page')
     ->attachFile('input-name', __DIR__.'/foo.txt')
     ->press('Submit');

It's important that you provide an absolute path to the file you wish to attach. Don't use a relative path.

press($submitText)

Not to be confused with click, the press method is used to submit a form with a submit button that has the given text.

$this->visit('search')
     ->type('Total Recall', '#q')
     ->press('Search Now');

When called, this package will handle the process of submitting the form, and following any applicable redirects. This means, we could combine some of previous examples to form a full integration test.

$this->visit('/search')
     ->type('Total Recall', '#q')
     ->press('Search Now')
     ->andSee('Search results for "Total Recall"')
     ->onPage('/search/results');

submitForm($submitText, $formData)

For situations where multiple form inputs must be filled out, you might choose to forego multiple type() calls, and instead use the submitForm method.

$this->visit('/search')
     ->submitForm('Search Now', ['q' => 'Total Recall']);

This method offers a more compact option, which will both populate and submit the form.

Take special note of the second argument, which is for the form data. You'll want to pass an associative array, where each key refers to the "name" of an input (not the element name, but the "name" attribute). As such, this test would satisfy the following form:

<form method="POST" action="/search/results">
  <input type="text" name="q" placeholder="Search for something...">
  <input type="submit" value="Search Now">
</form>

seeInDatabase($table, $data) or verifyInDatabase($table, $data)

For situations when you want to peek inside the database to verify that a certain record/row exists, seeInDatabase or its alias verifyInDatabase will do the trick nicely.

$data = ['description' => 'Finish documentation'];

$this->visit('/tasks')
     ->submitForm('Create Task', $data)
     ->verifyInDatabase('tasks', $data);

When calling verifyInDatabase, as the two arguments, provide the name of the table you're interested in, and an array of any attributes for the query.

Important: If using the Laravel-specific extension, this package will use your existing database configuration. There's nothing more for you to do. However, if using the Goutte or Selenium extensions, you'll need to create either a integrated.json or integrated.php file in your project root, and then specify your database connection string. Here's a couple examples, using the JSON file option:

SQLite Config

{
    "pdo": {
        "connection": "sqlite:storage/database.sqlite",
        "username": "",
        "password": ""
    }
}

MySQL Config

{
    "pdo": {
        "connection": "mysql:host=localhost;dbname=myDatabase"
        "username": "homestead",
        "password": "secret"
    }
}

To negate the assertion, you may use notSeeInDatabase or notVerifyInDatabase.

seeFile($path)

To ensure that a file exists, you may use the seeFile method.

To negate the assertion, you may use notSeeFile.

dump()

When you want to quickly spit out the response content from the most recent request, call the dump method, like so:

$this->visit('/page')->dump();

This will both dump the response content to the console, and save it to a tests/logs/output.txt file, for your review. Please note that this method will die. So no tests beyond this call will be fired. Nonetheless, it's great for the times when you need a better look at what you're working with, temporarily of course.

Selenium

Because Selenium works with an actual browser, there is an extended API that is specific to this extension.

Don't forget that, just as with the rest of the API, you may precede the word "and" to any method, if it helps with readability.

seeInAlert($text, $accept = true)

If an alert box should be displayed at some point, you can assert that it contains your given text with this method.

    /** @test */
    public function it_sees_things_in_alert_boxes()
    {
        $this->visit('/page-with-alert')
             ->seeInAlert('I am an alert');
    }

snap($destination)

If you'd like to take a snapshot of the current page, doing so is a cinch with Integrated.

    /** @test */
    public function it_sees_things_in_alert_boxes()
    {
        $this->visit('/page')
             ->snap();
             
    }

By default, a PNG of the current page (at the time you call snap()) will be saved to ./tests/logs/screenshot.png. However, of course, you may override this: snap('./path/to/save').

waitForElement($element, $timeout = 5000)

In many cases, such as for AJAX requests, you'll want Selenium to wait for a set amount of time, until something displays on the page (such as a confirmation box). In situations such as this, we can instruct Selenium to continue polling the page for an element/tag with the given name or id. Once it finds the element, only then does it continue on to your next assertion.

Because we don't want Selenium to poll forever, a timeout is provided. This defaults to 5 seconds, however, feel free to set this to whatever you want.

    /** @test */
    public function it_sees_things_in_alert_boxes()
    {
        $this->visit('/page-with-ajax')
             ->waitForElement('confirmation')
             ->andSee('Success!');
             
    }