Dawn

Dawn is an experimental browser-testing library for Laravel. It aims to be mostly compatible with Dusk, but with different trade-offs¹. The main benefit of Dawn is that it allows you to write browser tests exactly as you write all other feature tests (database transactions, mocks, custom testing routes, etc). This generally means that they run faster and with fewer restrictions.

Warning This is a very early release. Some edge-cases have been accounted for. Many have not. Much of the Dusk API has been implemented, but plenty of methods and assertions are missing.

Installation

Install Dawn

You can install the development release of Dawn via Composer (you'll need PHP 8.1 and Laravel 9):

composer require glhd/dawn:dev-main

Install Chrome Driver globally

You'll also need chromedriver installed on your machine.

Note Eventually, Dawn will install a copy of chromedriver for you, just like Dusk. The current implementation has only been tested on MacOS with chromedriver installed via homebrew. YMMV.

Usage

To use Dawn, add RunsBrowserTests to any test case. Then you can call openBrowser() to get a Browser instance to start testing with.

class MyBrowserTest extends TestCase
{
  use RefreshDatabase;
  use RunsBrowserTests;
  
  public function test_can_visit_homepage() 
  {
    $this->openBrowser() // <-- this is Dawn
      ->visit('/')
      ->assertTitleContains('Home');
  }
}

Dawn API

Dawn aims to have an API that is mostly compatible with Laravel Dusk. Not all features or assertions are implemented, but for right now you're best using the Dusk documentation for reference.

Differences from Dusk

The primary API difference between Dawn and Dusk is that the Dawn APIs do not require browser interactions to happen inside of callbacks. For the most part, this just involves replacing calls to $this->browse() with $this->openBrowser() and removing the closure:

-$this->browse(function ($browser) {
+$browser = $this->openBrowser();
$browser->visit('/login')
-});

There are certain Dusk methods are either tricky to implement with Dawn's async I/O channel, or are impossible to recreate exactly due to serialization constraints (you cannot serialize a TCP connection, for example). Here are some such functions:

• login(), loginAs(), etc — these don't make any sense in Dawn, because you can just use the normal actingAs() or be() helper methods in your test.
• cookie() and plainCookie() — these will eventually be implemented
• element() and elements() — because Dawn interacts with the WebDriver instance in a background process, it is a little harder to get direct access to the underlying RemoteWebElement instances in your main PHPUnit process. There will eventually be an API for accessing these, but it will likely work slightly differently.
• ensurejQueryIsAvailable() — Dawn does not rely on jQuery

Dusk API Compatibility

Much of the Dusk API has been implemented, but not all of it.

Missing methods (may not be exhaustive):

• pressAndWaitFor()
• within()/with()/elsewhere()/elsewhereWhenAvailable() (scopes are generally not implemented yet)
• onComponent() (components aren't implemented yet)

Missing assertions (may not be exhaustive):

• assertVueContains()
• assertVueDoesNotContain()
• assertQueryStringHas()
• assertQueryStringMissing()

Troubleshooting

I get an error like `Failed to connect to localhost port 9515 after 2 ms: Couldn't connect to server`

Make sure you have both `chromedriver` and the same version of Google Chrome installed.

FAQ

Does it work on anything other that Chris's Mac?

🤷‍♂️

Will it ever work on Windows?

🤷‍♂️ Probably?

When can I use this?

Fortune favors the brave.

Is this the final API?

Most of the `RunsBrowserTests` is pretty solid. The underlying implementation may change a ton before 1.0.

Major TODO Items

• Finish copying over the Dusk API
• Full test coverage
• Get automated tests running on Windows
• Improve the chromedriver installation/etc story
• Get drag and drop working

Footnotes

1. Dawn is generally easier to use out of the box, but writing custom low-level WebDriver code is trickier due to how Dawn works under the hood. ↩