What’s a flaky test?

It’s a test that sometimes fails, but if you retry it enough times, it passes, eventually.

Quarantined tests

When a test frequently fails in master, a ~”master:broken” issue should be created. If the test cannot be fixed in a timely fashion, there is an impact on the productivity of all the developers, so it should be placed in quarantine by assigning the :quarantine metadata.

This means it will be skipped unless run with --tag quarantine:

bin/rspec --tag quarantine

Before putting a test in quarantine, you should make sure that a ~”master:broken” issue exists for it so it won’t stay in quarantine forever.

Once a test is in quarantine, there are 3 choices:

  • Should the test be fixed (i.e. get rid of its flakiness)?
  • Should the test be moved to a lower level of testing?
  • Should the test be removed entirely (e.g. because there’s already a lower-level test, or it’s duplicating another same-level test, or it’s testing too much etc.)?

Quarantine tests on the CI

Quarantined tests are run on the CI in dedicated jobs that are allowed to fail:

  • rspec-pg-quarantine (CE & EE)
  • rspec-pg-quarantine-ee (EE only)

Automatic retries and flaky tests detection

On our CI, we use RSpec::Retry to automatically retry a failing example a few times (see spec/spec_helper.rb for the precise retries count).

We also use a home-made RspecFlaky::Listener listener which records flaky examples in a JSON report file on master (retrieve-tests-metadata and update-tests-metadata jobs).

This was originally implemented in: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13021.

If you want to enable retries locally, you can use the RETRIES environment variable. For instance RETRIES=1 bin/rspec ... would retry the failing examples once.

Problems we had in the past at GitLab

Time-sensitive flaky tests

Array order expectation

Feature tests

Capybara expectation times out


Return to Testing documentation