Testing

Snipe-IT uses PHPUnit and Laravel Dusk as automated testing frameworks. We adhere to the Laravel way of doing things, which means our tests are broken down as described below. All tests are located in the tests directory of your local Snipe-IT installation.

❗️

If your tests break the CI build, or if you do not provide any tests with a new feature, your PR will not be accepted. Make sure you run the full test suite locally before submitting your PR to ensure your changes did not break existing functionality.

Unit Tests

These are located in tests/Unit and are usually small tests that check the results of model methods. We typically do NOT check built-in Laravel validation or Eloquent relationships, and where possible, we avoid using factories or interacting with the database. (It's fine if your unit tests do need to interact with the database, it just slows things down a bit.)

Run these using phpunit or ./vendor/phpunit/bin from the command line in your local Snipe-IT project folder.

Feature Tests

These are located in tests/Feature and handle less-complex "real world" application testing, and API testing. Basically anything where we need to test for an HTTP response, but we don't need to actually run a headless browser that emulates an actual human being clicking around. (In some schools of testing thought, these might be called integration or functional tests.)

Run these using phpunit or ./vendor/phpunit/bin from the command line in your local Snipe-IT project folder.

Browser Tests (via Laravel Dusk)

Browser tests (often called acceptance tests) are located in tests/Browser and are used to launch a headless Chrome browser and actually perform the actions requested, such as clicking on a specific button and looking for a certain string in the resulting response.

Run these using php artisan dusk from the command line in your local Snipe-IT project folder.

Browser tests tend to be expensive to run (read: slow), so consider whether they are actually necessary for your pull request. Generally speaking, unless your pull request is manipulating the DOM or interacting with javascript in some way, Feature tests will suffice, but it will really depend on what you're submitting. If you're not sure, just ask by opening up a Github issue about the problem you're trying to solve.

Writing Unit Tests

You can reference the ExampleTest.php in the tests/Unit directory for an example of how tests in general should look.

<?php

namespace Tests\Unit;

use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    /**
     * A basic test example.
     *
     * @return void
     */
    public function testBasicTest()
    {
        $this->assertTrue(true);
    }
}

to:

To generate a new Unit test, use:

php artisan make:test MyModelTest --unit

which will generate the scaffolding for your new Unit test in the tests directory.

Please update the generated PHP docblock in your tests from:

/**
* A basic test example.
*
* @return void
*/

to:

/**
* @test
*/

Using Factories

We lean on factories to generate realistic-looking data for testing. You can find those in database/factories, and they can be invoked in a Unit test.

🚧

The default scaffolding won't work out of the box if you're using factories to generate data within your Unit tests

If you wish to use factories in your Unit tests, you MUST change the use statement at the top of your test from:

use PHPUnit\Framework\TestCase;

to:

use Tests\TestCase;

in order to access factories within a Unit test.

If you don't make this change, you will likely see an error that looks like this:

InvalidArgumentException: Unable to locate factory with name [default] [App\Models\MyModel].