Working With Tests - itinerare/Aldebaran GitHub Wiki
Aldebaran includes a full suite of tests for its various functions, utilizing Laravel's support for testing through PHPUnit. These tests run though different scenarios for different areas of the project, checking for expected behavior.
Consequently, it's recommended when modifying Aldebaran to, at minimum, run tests for the area(s) of it that you are modifying. While all tests are run automatically on creation of a pull request, running tests before this point can catch a failing result beforehand, allowing you to make any changes necessary.
Note that it may take some time to run the full test suite; this is why running only the relevant tests is expressly recommended.
Additionally, the tests are not all-encompassing. Some things must be manually tested and/or verified as a consequence of how tests are run. The current list of these is as follows:
- Processed images are as expected, visually; image processing itself is tested for errors
- Sort behaves as expected
- General aesthetics are functional/as expected/UI elements are visually clear in both desktop and mobile views
- Two-factor authentication
- Captcha works as expected
- Note that there is no visible element to it.
- Backups work as expected
- Emails are formatted as expected
- Payment processor integrations (Stripe, PayPal) work as expected
Before running tests for the first time, you will need to create a database for test purposes. The test database will be repeatedly cleared and re-formed, so it's important for it to be separate from your development database.
By default, the tests are configured to run on a database named
aldebaran_test. It's recommended to create a database with this name.
If you ordinarily access your local mySQL or equivalent via root with no password, you can proceed to testing. If not, it is recommended create a testing .env. This can be done by creating a file named
.env.testing alongside your existing .env file; one option is to make a duplicate of it and adjust the following values:
APP_ENV=testing DB_DATABASE=aldebaran_test DB_USERNAME=(USERNAME HERE) DB_PASSWORD=(PASSWORD HERE)
If the username you use for this is not root, you may also need to adjust phpunit.xml (located alongside your .env file) with the username. Be careful not to commit this change!
Tests can be run via the
php artisan test command. However, on its own this will run all tests, which as mentioned takes some time. As a result, it is recommended to filter this down to only the relevant tests.
This can be done via use of
--filter followed by some term-- the name of a group of tests, for instance. An effort has been made to name test files in mutually exclusive ways to assist with this.
For example, the following command would run the tests contained in the
php artisan test --filter AdminTextPage
It is recommended to filter tests by file name in this fashion; individual tests, while named descriptively, are aimed at being identifiable in results moreso than being filtered by.
When running tests, it's important to note that the tests are a helpful tool to identify potential issues, but are not absolute. For instance, if a test (that previously succeeded) fails, there are a couple potential reasons:
- The changes you have made to the code have introduced an issue that prevents expected behavior from occurring.
- The changes you have made have changed the expected behavior such that the tests are no longer accurate.
- This means that the tests must be updated to match the new expected behavior! (See Writing and Modifying Tests below.)
In either circumstance, the failing test(s) will be identified to give you an idea of where to look.
Conversely, a passing result does not necessarily mean everything is bug-free! It does, however, mean this is more likely.
The following is a list of all test files present in Aldebaran as of the time of writing, as well as a summary of their contents. Tests generally contain tests for both accessing relevant routes as well as making changes to objects where appropriate.
Admin Function Tests
These relate to functions available through the admin panel/only accessible to the singular/admin account.
- Tests editing account settings for the admin account.
- Tests creation and editing of changelog entries.
- Tests admin viewing and editing of individual commissions.
- Tests admin creation and editing of mailing list entries.
- Tests admin kicking and banning of mailing list subscribers.
- Tests admin creation and editing of mailing lists.
- Tests admin viewing of commission queues, the ledger, and fee calculation.
- Tests uploading of site images.
- Tests editing of site settings.
- Tests editing of text pages.
These relate to editing site data, and are categorized down further by gallery- and commission-relatedness.
- Tests creation and editing of piece images.
- Tests creation and editing of piece literatures.
- Tests creation and editing of pieces.
- Tests creation and editing of programs/media.
- Tests creation and editing of projects.
- Tests creation and editing of tags.
- Tests creation and editing of commission categories.
- Tests creation and editing of commission classes.
- Tests creation and editing of commission types.
These relate to viewing public-facing commission info and submitting commission requests.
- Tests viewing and submitting the commission request form as well as viewing commissions.
- Tests viewing commission and commission type info, example galleries, terms of service, public-facing queue, and custom pages related to commission classes.
These test public view of general information on the site.
- Tests public view of the changelog and entries.
- Tests public view of feeds and the feed index.
- Tests public view of the gallery as well as projects.
- Tests public view of text pages.
Other Site Function Tests
These test public access to miscellaneous site functions.
- Tests the contents of various emails that site functions can send.
- Tests public mailing list view and subscription, verification, and unsubscription.
These test basic site functionality.
- Broad tests of the middleware governing access to different areas and functionality.
- Tests login and logout. Does not test for 2FA.
Writing and Modifying Tests
Depending on the nature of the changes you are making, you may need to add and/or modify existing tests. If the changes you are making necessitate it-- for instance, they change the circumstances under which an operation is performed in a way that impacts an existing test, or add new functionality-- adding to and/or updating tests is required.
Laravel's documentation for testing can be found here, with the articles on HTTP Tests and Database Testing being most relevant. Aldebaran's tests make extensive use of PHPUnit's features as well, such as data providers, so it's recommended to reference the PHPUnit documentation as well.
You should strive to maintain the existing formatting, naming, etc. conventions. The existing tests are broadly commented to aid in this endeavor as well as test modification itself.
Similarly, when writing tests, you should strive to cover a variety of possible circumstances, such as:
- Viewing a page under various circumstances
- ...without any objects (as applicable)
- ...with objects (as applicable)
- Creating and editing, as well as deleting, an object
- ...including getting the relevant routes
- ...with minimal data
- ...with different kinds of data (as applicable)
...and/or any other situations that are relevant to your changes. Of course, you can view the existing tests for some examples of this.
Factories (see the Database Testing article linked above) are utilized for convenient creation of objects for testing purposes. Most of the objects present in Aldebaran are accounted for by default; these factories may be used in writing your own tests or making alterations to existing ones.
In the instance that your changs involve alterations to a model that impact the functionality of an existing factory, or you are creating a model which would benefit from one, you must also modify and/or create factorie(s) as appropriate. Similarly, in creating and editing factories you should strive to maintain existing formatting, etc.