Testing a Rails Template
As promised in my previous post, here is part 2 of my series on Rails Templates. Last time, I showed you how to create them, now we're going to look at how to test them. If you haven't ready part 1, I highly recommend you do so before delving into the testing process.
Testing a Rails Template can feel pretty meta. Whereas you'd normally be testing functionality of a Rails app, here you are testing the very creation of a Rails app - one that adheres to specifications you designed. And while that can be a bit mind-bending, it is absolutely essential if you intend for you or your team to actually use the template. Below, I'll outline a few ways to ensure your template is working the old-fashioned way - with tests!
As you customize your template, run the $ rails new command referencing the template as often as possible. If there are any issues in your syntax or order-of-operations, the command line will let you know. But even when your template is generated successfully, do not assume that the Rails app you just created is error-free. Every time you generate an app with your template, bang on it manually as frequently as possible.
Using this approach, we caught that we'd missed a line in the rails_helper telling it to read from support files for gem configs. Another common mistake is incorrect indentation inside your template, which can break a .yml file entirely. Don't leave these mistakes to your team to catch. If you're lucky, they'll mention them to you, but they might just stop using the template if it's causing them problems.
Linting runs a program that analyzes your code for style inconsistencies, deprecated methods, and many other potential issues. At Smashing Boxes, we use Rubocop to lint our code. The template itself can be linted on your local computer by including a .rubocop.yml file with your company's styleguide. You can lint both the template itself and the apps you generate with the template.
Continuous Integration Tests
The most effective way you can test your Rails Template is to give it continuous integration test coverage. We use Travis at Smashing Boxes, but there are plenty of other great options, such as Circle CI. The goal of this type of test is to mimic the creation of a Rails app from scratch using your template. Check out the continuous integration specs for Boxcar.
When writing your CI specs, there are some important starting points to remember:
1. before_script: Travis allows a before_script. This is precisely where all the preparation before we can begin creating a template comes in.
gem install rails --no-ri --no-rdoc
- With a Rails template, we are creating a Rails app from scratch, so the first thing we must do is install the Rails gem.
2. Generate the Rails app! Check out an example from Boxcar.
printf 'y\nn\ny\ny\nn' | rails new api_only_app -m boxcar/template.rb -B
- If you have any options inside of your template, it is critical that you create one of each possible version. Responses can be automated within Travis:
- Be sure to `cd` out of each template before the creation of each version. Otherwise, you may accidentally create a Rails app inside another Rails app, which will certainly create confusion for your specs.
3. Prep your newly created app for testing. `cd` into the app to do the following:
- Ensure that your app has access to any crucial info - like a database.yml and a secrets.yml. At Smashing Boxes, we use database.example.yml and secrets.example.yml. In this case, be sure to copy them over to your app.
- Run the commands rake db:migrate and rake db:test
- Copy over all sample test files: These are files you create inside your template for this exact purpose. Some examples:
- Rspec spec.rb - this file will verify that Rspec is in fact working inside your template. If the spec does not pass or get called correctly, this is a great indicator that something in your Rspec configuration failed to generate successfully.
- Cucumber feature spec + step definition: this spec will verify that Cucumber has installed correctly, if applicable.
4. script: Now that your template has been generated, you are ready to run your tests! Within the script is where you actually test the template(s) you've just generated.
- Run your local linter on the template itself.
- Inside the app you've created, run your local linter, rspec, cucumber (if applicable) and any other specs you'd like to test.
5. Remember to repeat Step #2 for any other versions of the template you have generated.
Your CI tests are excellent tools for catching any changes to auto-generated files or deprecated syntax issues, and for upping your confidence that apps spun up with your template will be an excellent starting point for your team. But don't rely on them entirely. As you continue to make edits, be sure to mix in some manual tests as well. With a combination of these approaches, your Rails template is sure to be a huge hit!