APIs

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) (upcoming release)

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) (upcoming release)

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>