Skip to content

Dusk

Introduction

We use Laravel Dusk for front-end testing. Dusk is a browser automation and testing API for Laravel applications. It is built on top of the ChromeDriver and allows us to run browser tests in a headless Chrome browser. The rest of this entry will cover local implementation and some usage specifics but see the official Laravel Dusk documentation for more information.

Local Setup

Dusk-specific environment file

Create a .env.dusk.local file in the root of your project. This file should contain the same environment variables as your standard .env file, but with the following important differences:

  • APP_ENV set to dusk
  • DB_DATABASE set to a new unique SQL database you must create, such as flowcode_dusk
  • TEST_USER_EMAIL - get value from Paul or Zoho Vault entry
  • TEST_USER_PASSWORD - get value from Paul or Zoho Vault entry
  • TEST_USER_UID - get value from Paul or Zoho Vault entry

Dusk will use this environment file to run its tests. The TEST_USER variables are used by LoginTest so that a valid Firebase user can be used.

Writing Tests

Location

Dusk tests are located in the tests/Browser directory.

Extending DuskTestCase

Each test should extend DuskTestCase which has been set up with a number of traits, and methods. The setUp method there is particularly important as it migrates and seeds the testing database in a manner that is compatible with Envoy's multitenant architecture.

Seeding

Seeding should be used to create any data needed for testing. A custom seeder class called DuskSeeder has been created for use by DuskTestCase, so new seeders can be added to this class if they are applicable to all or most new tests.

Alternatively you can call

Artisan::call('db:seed', [
    '--class' => SeederNameHere::class
]);

directly in your test.

Dusk Selectors

In front-end components you can use the dusk attribute to identify elements for Dusk to interact with. For example:

<button dusk="login-button">Login</button>

This can then be interacted with in a Dusk test like so:

$browser->click('@login-button');

Note that the dusk attribute is not accessible to Dusk when applied to our Salt Admin Component Library components. If you need to interact with one of these legacy components you should convert it to a local component where the dusk attribute can be successfully used.

Running Tests

Run the Dusk test suite with the php artisan dusk command. This will run all tests in the tests/Browser directory.