Awesome
Test
Test is an Ash module that offers easy unit testing, with simple CI integrations.
Running Tests
You can run tests by running the following command:
ash test $module-to-test
Where $module-to-test
is either a module alias, or a module package.
Hooking Up a Module to Travis
You can generate the .travis.yml
file by running the following command while in your modules directory:
ash test:travis
If your tests are already written, there is no further configuration you need to do beyond enabling your repository on Travis.
Writing Tests
The ash_config.yaml
File
To get started with writing tests, you must first add a test_prefix
key to your modules ash_config.yaml file.
For example, if our module was named Slugify
, we would add this line here:
test_prefix: Slugify
The test.sh
File
Now that we're ready to start writing tests, we'll have to create the test.sh
file at the root of our module.
If you'd like to check out what a fully built test.sh file looks like before we jump in, check out Slugify's
In the test.sh
file, you can create functions that start with "$test_prefix"__test_
, and those will get run when we run our tests.
Following our previous example, if our module was named Slugify
, the functions that we would want to test would have to start with Slugify__test_"
When writing these functions, if at any point there is a failure you should return 1. When everything succeeds don't return anything.
Here is a test from Slugify:
Slugify__test_slugify_spaces(){
# Space in the middle of a sentence
Slugify_test_single_slugify "Brandon Romano" "brandon-romano"
if [[ $? -ne 0 ]]; then return 1; fi
# Multiple Spaces
Slugify_test_single_slugify "Radical Ricky" "radical-ricky"
if [[ $? -ne 0 ]]; then return 1; fi
}
Conventions to Follow to Write Great Tests
Test provides some really great tools to help you write really great tests, but you should definitely follow a few conventions.
Before jumping into this section, I will provide a screenshot that displays what a test looks like (with a forced failure):
All that fancy indentation is handled for you :tada:
Provide Concise Names for Tests
The name of your actual test method has to start with "$test_prefix"__test_
by requirement, but anything after that is up for you to decide.
Your test names should describe the module you are testing, as the test name is used in the output of the tests.
For example, if we had a test Slugify__test_slugify_spaces
, when running the test we would see test_slugify_spaces
in both success and failure cases.
The names are very important, as this is the only piece of information we see during a successful run of a test (as you can see above).
Provide a Fluent Failure Description
For a failing test, we should always provide a description of what went wrong. The error message should be written for the context of the error message above (The first line with the unicode red arrow is the Description
, the lines below it are the details). These descriptions should be concise.
Failure descriptions are the first line that is echoed out in a test function.
For example:
Slugify__test_slugify_spaces(){
local result="$(Slugify__slugify "Radical Ricky")"
if [[ "$result" != "radical-ricky" ]]; then
# This line below is our failure description
echo "Slugify__slugify should convert 'Radical Ricky' into 'radical-ricky'"
return 1
fi
}
Provide Futher Details if Needed
I would argue that most of the time further details are actually needed. Any additional lines echoed out are further details.
Following our previous example, we probably would want to know the actual result of the output if it weren't what we were expecting:
Slugify__test_slugify_spaces(){
local result="$(Slugify__slugify "Radical Ricky")"
if [[ "$result" != "radical-ricky" ]]; then
# This line below is our failure description
echo "Slugify__slugify should convert 'Radical Ricky' into 'radical-ricky'"
# This lines below are our failure details. We can have as many (or as little) of these as we want
echo "Actual Result: '$result'"
echo "Wow, another detail!"
return 1
fi
}