- 1 Overview
- 2 Test Helpers
- 3 Resource Tests
- 4 API Tests
- 5 Context
- 6 Schema Validation
- 7 Testing Spectrum
- 8 Double-Testing Units
- 9 Generators
Wait, hear me out!
Even if you’re not a fan of TDD, Graphiti integration tests are simply the easiest, most pleasant way to develop. In fact, most Graphiti development can happen without even opening a browser. And as a side effect, you get a reliable test suite.
Let’s say we want to filter Employees by
title, which comes from
positions table. Start with a spec:
By developing test-first:
- We don’t need to struggle with seeding local development data or finding the right records for specific scenarios - we can seed randomized data on-the-fly with factories.
- There’s no need to spin up a server and refresh browser pages, mentally parsing the response payload.
- We get a high-confidence test “for free”.
- Because our integration test is separate from implementation, we don’t need to worry about test-induced design damage.
1.1 API vs Resource
There are two types of Graphiti tests: API tests and Resource tests.
This is because the same Resource logic can be re-used at multiple
endpoints. PostResource can be referenced at
/admin/posts, but we shouldn’t have to test the same filtering and
sorting logic over and over. Querying, persistence, and serialization are
all Resource responsibilities, tested in Resource tests.
We still want API tests, though, to test everything outside of the Resource: routing, middleware, cache rules, response codes, etc…
Typically, you’ll write the API test once and not have to touch it again.
Note: Factories are not required, but they are considered a best practice used by the Graphiti test generator. Read thoughtbot’s Why Factories? for more information.
When you generate a model, a stub factory will be created. It is highly recommended you edit that factory with randomized data:
This will help catch edge cases and provide more clarity than seeing the
It’s a best practice that if a factory defines an attribute, there should be a corresponding validation around that attribute. If an attribute is optional, it should not be defaulted in a factory.
Finally, Rails 5 made belongs_to required by default. This means that if Employee
belongs_to :department, then
create(:employee) will fail. To ensure a relationship is always seeded:
RSpec is not required, but considered a first-class citizen used by the Graphiti test generator.
2 Test Helpers
Tests are run using JSONAPI standards. But the JSONAPI payload can be a pain to deal with. So, we’ve supplied helpers.
These helpers are defined in the Graphiti Spec Helpers gem.
Note: for brevity, this method is aliased to
jsonapi_data method will parse response data and return a
normalized object (
GraphitiSpecHelpers::Node). Assert against this the same way you assert against
idwill automatically case to an integer. If you would like to avoid this, use
jsonapi_typeis a convenience method for
data/type, to avoid conflicting with an attribute of the same name.
- If the
first_namekey was not present in the response, an error will be raised.
2.2 Accessing Sideloads
To grab a relationship:
sideload method accepts the name of the relationship. It returns
GraphitiSpecHelpers::Node containing the
2.3 Accessing Links
To grab a Link:
This accepts the relationship name and the link type. It will return the link URL.
To see the raw JSON response, use
2.3 #date and #datetime
In Graphiti, datetimes are rendered in ISO 8601 format. This means that straight date comparisons will fail:
Instead, use the
datetime helper to convert to ISO 8601 and compare
apples to apples:
Similarly, there’s a
date helper as well.
This method is aliased to
To parse an Errors Payload:
2.5 Resource Test Helpers
Resource tests have two helpers, both different ways to execute a query.
render will fire the query and return a JSON response that can be
accessed as normal:
records will return model instances:
2.6 API Test Helpers
When executing an API test request, always use the
jsonapi_get(url, params:)instead of
jsonapi_post(url, payload)instead of
jsonapi_put(url, payload)instead of
jsonapi_patch(url, payload)instead of
This will set the
CONTENT_TYPE header to
to_json on the payload (when applicable).
It also allows overriding
jsonapi_headers. Use this to manipulate
headers for a given request:
2.7 Guard Helpers
Many teams use guard in development to watch their project files and run a smaller set of focused tests as code changes. For those teams leveraging guard and the guard-rspec plugin, we offer an additional set of DSL helpers via the guard-rspec-graphiti plugin. For more details, check out the project README.
3 Resource Tests
There are two test files for each Resource:
The basic setup for read operations:
We want to test that our attributes render correctly. We’ll do this by seeding a record, firing a basic query, and comparing the JSON result to the seeded data.
- Assert on all attributes, even if there is no logic. This way adding logic will cause a test failure.
- When seeding data, manually assign values. This way you can be assured
you aren’t accidentally testing
nil == nil
If you decide you have a high level of confidence in your factories, you can instead save some keystrokes and assert on randomized data:
Note: Our schema validation test will ensure no attributes get removed or change types.
Here we seed data, set the filter parameter, and assert only records matching the given criteria are present in the response.
In general, you only need to test filtering when there is custom logic. Our schema validation test will ensure no filters are removed, guarded, changed operators, etc.
Here we seed data, set the sort parameter, and assert the correct order of the rendered response.
In general, you only need to test sorting when there is custom logic. Our schema validation test will ensure no sorts are removed, guarded or limited in direction.
Here we seed data, set the sideload parameter, and assert the correct entity is present in the request. There is no need to test each attribute of the sideload - this should be tested in the Resource Test of the sideloaded Resource.
In general, you only need to test sideloads when there is custom logic. Our schema validation test will ensure no sideloads are removed or associated to a different Resource.
The basic setup for write operations:
payload is a JSONAPI Resource Object.
payload is an empty Employee Resource Object.
We’ll assert that when saving this empty payload, an Employee is
You’ll likely want to add attributes here and ensure they are persisted correctly:
126.96.36.199 Required Belongs To
Rails 5 made belongs_to required by default. This means that if Employee
belongs_to :department, the above tests will fail (we cannot create the Employee without associating it to Department).
You have 3 options here:
- Turn off this validation in test mode. Add
config.active_record.belongs_to_required_by_default = falseto
- Turn off the validation for this specific relationship:
belongs_to :department, optional: true.
- Associate as part of the request.
We recommend the third option to preserve real-world end-to-end behavior:
Will ensure the Employee is created and associated to the given department.
Note that this test will be pending by default when using the generator, as we require the attributes to be explicitly defined.
payload is an empty Employee Resource Object.
We’ll assert that when updating attributes, the changes are correctly
persisted to the database.
Here we ensure that a delete request correctly removes a record from the database.
3.2.4 Side Effects
It’s common for write operations to cause side-effects, such as sending an email or updating an audit trail. It’s recommended to test these within the same “it” block unless the logic gets particularly intense. Though “one expectation per test” works well for unit tests, integration tests can take longer to run and the performance penalty isn’t worth it.
4 API Tests
There are five test files for each Resource:
Here we’re ensuring
EmployeeResource is the correct resource to be
called from this endpoint, we get a 200 status code, and the entities
returned are expected.
index, but fetching only a single Employee.
Here we’re ensuring EmployeeResource is called, a record is correctly
inserted, and the response code is
You probably only want to add attributes required to pass validation, here - note that we don’t assert on attributes of the created record (save this for your Resource test). One easy way to do this is to pass randomized data from your factory:
Here we’re ensuring EmployeeResource is called, attributes are updated, and we respond with a 201. Note that we don’t assert on specific attributes - save that for your Resource test.
Just like the prior section, you may want to leverage FactoryBot here to generate randomized attributes:
Here we’re sending a DELETE request, ensuring the record is actually removed, and we respond according to the JSONAPI specification.
Occasionally you’ll need to set context for tests. The most common scenario is authorization:
When using Rails,
context is the controller associated to the request.
We can manually set context in tests:
6 Schema Validation
Graphiti comes with built-in backwards-compatibility tests. We do this by comparing the current version of the schema with one previously checked-in.
These tests are added at the bottom of
Whenever you run tests, the schema check will also run. If we find any backwards-incompatibilities - attributes removed, types changed, default sort direction modified, etc - the schema test will fail with an output detailing all incompatibilities.
When the schema test succeeds, it will overwrite the existing schema file with the new schema. It will not do this on failure.
There are times when you want to accept an incompatibility and move on
anyway. In this case, use
7 Testing Spectrum
Testing standards vary from team to team, and there is no right answer when judging “the right level of testing”.
You could add tests for every attribute, validating every sort and
filter. Or, you could consider logicless configuration tested as part of
Graphiti itself (the same way we don’t tend to test a
ActiveRecord relationship). Though our guides favor the latter, the
extra tests could prove useful when performing a major upgrade or
You could do more API testing, particularly for high-value functionality. Testing fully end-to-end, from middleware to response codes, gives a high level of confidence. But it can also feel like duplicate tests across endpoints, which is why we have Resource tests.
Graphiti provides sensible defaults, but you’re encouraged to consider the tradeoffs and pick the right level of testing for you.
8 Double-Testing Units
Integration testing is great: it gives a high level of confidence, and they’re typically the easiest tests to write. In fact, these tests are so powerful the value of unit testing sometimes comes up for debate.
Consider a custom filter powered by an ActiveRecord scope:
If we’re by-the-book, we should absolutely test
.by_title on the
Employee model. After all, we’re exposing a public interface that other
developers might rely on in the future.
This can feel cumbersome, even duplicative. The Resource Test of the title filter will seed the same data as the corresponding unit test, and the assertion will be almost identical. But because Resource Tests are integration tests, we shouldn’t mock the code either.
The best practice here is to use RSpec shared_context to remove the duplication:
This allows our
by_title scope to be re-used by future developers
outside of the Resource context. It also keeps code clean and
But it’s not unreasonable to think the overhead here isn’t worth it. If you’re of this mind, we recommend testing the Resource and marking the method as not re-usable:
This way future developers know the scope is only an implementation detail and not considered part of this object’s public API. Writing the unit test can be deferred until the use case actually arises.
The Resource generator will create both Resource and API tests for you. Use these as templates to implement your tests.
You can also run
To generate only the API tests. This can be particularly helpful because
API tests are mostly boilerplate that does not need to be manually
edited. Pass the
-a option to limit RESTful actions.