Testing on Theseus
This page is the entry point for testing a modular feature on Theseus. It does not replace the GitLab-wide testing guidance. It sets out how that guidance applies here and links to it.
Before you start, have your service running locally in Caproni (see Run locally with Caproni). Most of what follows runs against it.
Your team owns your tests
Your team owns every test for your feature at every level, end-to-end included, and decides when your release is ready. See the handbook’s Testing Ownership Model.
| Who | Owns |
|---|---|
| Your team | Every test for your feature at every level, including any end-to-end coverage and any tests in the release gate. Triage when they fail. The decision that your release is ready. |
| Release teams | The deployment and release pipeline your tests run in, including where the release gate sits. |
| Theseus | The paved path: the service template, Caproni, and the testing pattern on this page. |
No team writes, maintains, or triages tests on your behalf. Questions about testing on Theseus go to #proj_theseus.
Test in this order
Reach for each layer only when the one before it cannot give you the signal you need. This is the test pyramid the rest of GitLab follows.
- Unit tests for your business logic.
- Contract and acceptance tests against fakes. The default, and where most of your confidence should come from: your real service, in-process fakes for its dependencies, and real infrastructure from Caproni. The modular feature test isolation strategy in this section explains the pattern and why it works, and the companion how-to shows how to build it.
- End-to-end tests on Caproni, for the few flows that genuinely span the stack. See Caproni’s test environments guide.
- End-to-end tests in the monolith, only where your feature has monolith tie-ins. See the next section.
“Do not write an end-to-end test if a lower-level feature test exists.”
When your feature ties into the monolith
If your feature has a UI surface, an API the monolith calls, or an auth flow
through Rails, coverage of that tie-in is also yours. It lives in the
monolith’s QA framework (qa/ in
gitlab-org/gitlab).
Contract tests on your side of the boundary still come first.
- End-to-end Testing: how the suite runs and how tests are selected in merge requests.
- Beginner’s guide to writing end-to-end tests: flows, page objects, and resources.
- RSpec metadata for end-to-end tests:
tag tests with
:product_groupso failures route to your team. - End-to-end test failure issue debugging guide: triaging the failures you own.
What the release gate is for
The release gate is the blocking end-to-end smoke suite that runs on the way to GitLab.com (see the deployment workflow). It protects critical functionality, and nothing more.
- A failure here is a high-severity event. It blocks deployment.
- Only gate on critical features. Add a test to the gate only if breaking that feature must stop a release.
- The gate is not a feature check. If you learn something new about your feature at the gate, a lower layer is missing a test. Add it there.
For how gate tests are tagged, see RSpec metadata. For which suites run against which environments, see End-to-end pipeline monitoring.