Skip to main content
Version: 0.1


This section covers the basics regarding how to test a Marten project and the various tools that you can leverage in this regard.

The basics

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 file allowing you to initialize the test environment for your Marten project.

This file should look something like this:

ENV["MARTEN_ENV"] = "test"

require "spec"
require "marten"
require "marten/spec"

require "../src/project"

As you can see, the 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.

Writing tests

To write tests, you should write regular specs and ensure that your spec files always require the spec/ file.

For example:

require "./spec_helper"

describe MySuperAbstraction do
describe "#foo" do
it "returns bar" do
obj = 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 file at each level of your folders structure. These additional files should require the same file from the parent folder.

For example:

require "../spec_helper"
require "./spec_helper"

describe Article do
# ...

Running tests

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| = "my_project_test"