This section covers the basics regarding how to test a Marten project and the various tools that you can leverage in this regard.
You should test your Marten project to ensure that it adheres to the specifications it was built for. Like any Crystal project, Marten lets you write "specs" (see the official documentation related to testing in Crystal to learn more about those).
By default, when creating a project through the use of the
new management command, Marten will automatically create a
spec/ folder at the root of your project structure. This folder contains a unique
spec_helper.cr file allowing you to initialize the test environment for your Marten project.
This file should look something like this:
ENV["MARTEN_ENV"] = "test"
As you can see, the
spec_helper.cr file forces the Marten environment variable to be set to
test and requires the spec library as well as Marten and your actual project. This file should be required by all your spec files.
It's very important to require
marten/spec in your top-level spec helper as this will ensure that the mandatory spec callbacks are configured for your spec suite (eg. in order to ensure that your database is properly set up before each spec is executed).
When it comes to running your tests, you can simply make use of the standard
crystal spec command.
To write tests, you should write regular specs and ensure that your spec files always require the
describe MySuperAbstraction do
describe "#foo" do
it "returns bar" do
obj = MySuperAbstraction.new
obj.foo.should eq "bar"
You are encouraged to organize your spec files by following the structure of your projects. For example, you could create a
models folder and define specs related to your models in it.
When organizing spec files across multiple folders, one good practice is to define a
spec_helper.cr file at each level of your folders structure. These additional
spec_helper.cr files should require the same file from the parent folder.
describe Article do
As mentioned before, running specs involves making use of the standard
crystal spec command.
The test environment
By default, the
new management command always creates a
test environment when generating new projects. As such, you should ensure that the
MARTEN_ENV environment variable is set to
test when running your Crystal specs. It should also be reminded that this
test environment is associated with a dedicated settings file where test-related settings can be specified and/or overridden if necessary (see Settings for more details about this).
The test database
Marten must use a different database when running tests in order to not tamper with your regular database. Indeed, the database used in the context of specs will be flushed and generated automatically every time the specs suite is executed. You should not set these database names to the same names as the ones used for your development or production environments. If test database names are not explicitly set, your specs suite won't be allowed to run at all.
One way to ensure you use a dedicated database specifically for tests is to override the
database settings as follows:
Marten.configure :test do |config|
config.database do |db|
db.name = "my_project_test"