2019-02-19 21:44:08 +00:00
# GitLab QA - End-to-end tests for GitLab
2017-02-20 11:45:04 +00:00
2019-05-22 01:34:12 +00:00
This directory contains [end-to-end tests ](../../../doc/development/testing_guide/end_to_end/index.md )
2019-02-19 21:44:08 +00:00
for GitLab. It includes the test framework and the tests themselves.
The tests can be found in `qa/specs/features` (not to be confused with the unit
tests for the test framework, which are in `spec/` ).
2017-02-20 12:18:41 +00:00
2017-10-05 10:36:28 +00:00
It is part of the [GitLab QA project ](https://gitlab.com/gitlab-org/gitlab-qa ).
2017-03-09 09:41:10 +00:00
2017-10-05 10:36:28 +00:00
## What is it?
2017-03-09 09:41:10 +00:00
2019-02-19 21:44:08 +00:00
GitLab QA is an end-to-end tests suite for GitLab.
2017-03-09 09:41:10 +00:00
2019-02-19 21:44:08 +00:00
These are black-box and entirely click-driven end-to-end tests you can run
2017-03-09 09:41:10 +00:00
against any existing instance.
## How does it work?
1. When we release a new version of GitLab, we build a Docker images for it.
1. Along with GitLab Docker Images we also build and publish GitLab QA images.
2019-02-19 21:44:08 +00:00
1. GitLab QA project uses these images to execute end-to-end tests.
2017-09-30 06:38:12 +00:00
2018-01-12 10:04:41 +00:00
## Validating GitLab views / partials / selectors in merge requests
We recently added a new CI job that is going to be triggered for every push
event in CE and EE projects. The job is called `qa:selectors` and it will
verify coupling between page objects implemented as a part of GitLab QA
and corresponding views / partials / selectors in CE / EE.
Whenever `qa:selectors` job fails in your merge request, you are supposed to
2019-05-22 01:34:12 +00:00
fix [page objects ](../doc/development/testing_guide/end_to_end/page_objects.md ). You should also trigger end-to-end tests
2018-03-19 09:04:23 +00:00
using `package-and-qa` manual action, to test if everything works fine.
2018-01-12 10:04:41 +00:00
2017-09-30 06:38:12 +00:00
## How can I use it?
2019-06-19 00:22:23 +00:00
You can use GitLab QA to exercise tests on any live instance! If you don't
have an instance available you can follow the instructions below to use
the [GitLab Development Kit (GDK)][GDK].
This is the recommended option if you would like to contribute to the tests.
### Run the end-to-end tests in a local development environment
Follow the GDK instructions to [prepare ](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/prepare.md )
and [install ](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/set-up-gdk.md )
your local GitLab development environment.
Once you have GDK running, switch to the `qa` directory. E.g., if you setup
GDK to develop in the main `gitlab-ce` repo, the GitLab source code will be
in a `gitlab` directory and so the end-to-end test code will be in `gitlab/qa` .
From there you can run the tests. For example, the
following call would login to the GDK instance and run all specs in
2017-09-30 06:38:12 +00:00
`qa/specs/features` :
```
2019-04-09 11:07:41 +00:00
# Make sure to install the dependencies first with `bundle install`
bundle exec bin/qa Test::Instance::All http://localhost:3000
2017-09-30 06:38:12 +00:00
```
2019-02-28 19:30:04 +00:00
Note: If you want to run tests requiring SSH against GDK, you
will need to [modify your GDK setup ](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/run_qa_against_gdk.md ).
2018-01-11 09:26:48 +00:00
### Writing tests
2019-05-22 01:34:12 +00:00
- [Writing tests from scratch tutorial ](../doc/development/testing_guide/end_to_end/quick_start_guide.md )
- [Best practices ](../doc/development/testing_guide/best_practices.md )
- [Using page objects ](../doc/development/testing_guide/end_to_end/page_objects.md )
- [Guidelines ](../doc/development/testing_guide/index.md )
2018-01-11 09:26:48 +00:00
2017-10-05 10:36:28 +00:00
### Running specific tests
You can also supply specific tests to run as another parameter. For example, to
2018-01-11 09:26:48 +00:00
run the repository-related specs, you can execute:
2017-09-30 06:38:12 +00:00
```
2019-07-11 01:01:32 +00:00
bundle exec bin/qa Test::Instance::All http://localhost:3000 -- qa/specs/features/browser_ui/3_create/repository
2017-12-20 11:03:10 +00:00
```
Since the arguments would be passed to `rspec` , you could use all `rspec`
options there. For example, passing `--backtrace` and also line number:
```
2019-07-11 01:01:32 +00:00
bundle exec bin/qa Test::Instance::All http://localhost:3000 -- qa/specs/features/browser_ui/3_create/merge_request/create_merge_request_spec.rb:6 --backtrace
2017-10-05 10:36:28 +00:00
```
2019-03-27 19:03:03 +00:00
Note that the separator `--` is required; all subsequent options will be
ignored by the QA framework and passed to `rspec` .
2017-10-05 10:36:28 +00:00
### Overriding the authenticated user
Unless told otherwise, the QA tests will run as the default `root` user seeded
by the GDK.
If you need to authenticate as a different user, you can provide the
`GITLAB_USERNAME` and `GITLAB_PASSWORD` environment variables:
```
2019-04-09 11:07:41 +00:00
GITLAB_USERNAME=jsmith GITLAB_PASSWORD=password bundle exec bin/qa Test::Instance::All https://gitlab.example.com
2017-09-30 06:38:12 +00:00
```
2018-02-08 14:34:56 +00:00
If your user doesn't have permission to default sandbox group
`gitlab-qa-sandbox` , you could also use another sandbox group by giving
`GITLAB_SANDBOX_NAME` :
```
2019-04-09 11:07:41 +00:00
GITLAB_USERNAME=jsmith GITLAB_PASSWORD=password GITLAB_SANDBOX_NAME=jsmith-qa-sandbox bundle exec bin/qa Test::Instance::All https://gitlab.example.com
2018-02-08 14:34:56 +00:00
```
2018-09-10 19:01:55 +00:00
All [supported environment variables are here ](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#supported-environment-variables ).
2017-10-05 10:36:28 +00:00
2018-11-28 13:11:05 +00:00
### Sending additional cookies
The environment variable `QA_COOKIES` can be set to send additional cookies
on every request. This is necessary on gitlab.com to direct traffic to the
canary fleet. To do this set `QA_COOKIES="gitlab_canary=true"` .
2018-12-28 16:06:08 +00:00
To set multiple cookies, separate them with the `;` character, for example: `QA_COOKIES="cookie1=value;cookie2=value2"`
2018-11-28 13:11:05 +00:00
2018-02-09 16:49:10 +00:00
### Building a Docker image to test
Once you have made changes to the CE/EE repositories, you may want to build a
Docker image to test locally instead of waiting for the `gitlab-ce-qa` or
2019-08-06 12:50:52 +00:00
`gitlab-ee-qa` nightly builds. To do that, you can run **from the top `gitlab`
directory** (one level up from this directory):
2018-02-09 16:49:10 +00:00
```sh
2019-08-06 12:50:52 +00:00
docker build -t gitlab/gitlab-ce-qa:nightly --file ./qa/Dockerfile ./
2018-02-09 16:49:10 +00:00
```
2017-10-05 10:36:28 +00:00
[GDK]: https://gitlab.com/gitlab-org/gitlab-development-kit/
2018-12-28 16:06:08 +00:00
### Quarantined tests
Tests can be put in quarantine by assigning `:quarantine` metadata. This means
they will be skipped unless run with `--tag quarantine` . This can be used for
tests that are expected to fail while a fix is in progress (similar to how
[`skip` or `pending` ](https://relishapp.com/rspec/rspec-core/v/3-8/docs/pending-and-skipped-examples )
can be used).
```
2019-07-11 01:01:32 +00:00
bundle exec bin/qa Test::Instance::All http://localhost:3000 -- --tag quarantine
2018-12-28 16:06:08 +00:00
```
If `quarantine` is used with other tags, tests will only be run if they have at
least one of the tags other than `quarantine` . This is different from how RSpec
tags usually work, where all tags are inclusive.
For example, suppose one test has `:smoke` and `:quarantine` metadata, and
another test has `:ldap` and `:quarantine` metadata. If the tests are run with
`--tag smoke --tag quarantine` , only the first test will run. The test with
`:ldap` will not run even though it also has `:quarantine` .
2019-03-27 19:03:03 +00:00
### Running tests with a feature flag enabled
Tests can be run with with a feature flag enabled by using the command-line
option `--enable-feature FEATURE_FLAG` . For example, to enable the feature flag
that enforces Gitaly request limits, you would use the command:
```
2019-07-11 01:01:32 +00:00
bundle exec bin/qa Test::Instance::All http://localhost:3000 --enable-feature gitaly_enforce_requests_limits
2019-03-27 19:03:03 +00:00
```
This will instruct the QA framework to enable the `gitaly_enforce_requests_limits`
feature flag ([via the API](https://docs.gitlab.com/ee/api/features.html)), run
all the tests in the `Test::Instance::All` scenario, and then disable the
feature flag again.
Note: the QA framework doesn't currently allow you to easily toggle a feature
flag during a single test, [as you can in unit tests ](https://docs.gitlab.com/ee/development/feature_flags.html#specs ),
but [that capability is planned ](https://gitlab.com/gitlab-org/quality/team-tasks/issues/77 ).
Note also that the `--` separator isn't used because `--enable-feature` is a QA
2019-04-09 11:07:41 +00:00
framework option, not an `rspec` option.