beginners_guide.md

stage: none
group: unassigned
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers

Beginner's guide to writing end-to-end tests

This tutorial walks you through the creation of end-to-end (e2e) tests for GitLab Community Edition and GitLab Enterprise Edition.

By the end of this tutorial, you can:

• Determine whether an end-to-end test is needed.
• Understand the directory structure within qa/.
• Write a basic end-to-end test that validates login features.
• Develop any missing page object libraries.

Before you write a test

Before you write tests, your GitLab Development Kit (GDK) must be configured to run the specs. The end-to-end tests:

• Are contained within the qa/ directory.
• Should be independent and idempotent.
• Create resources (such as project, issue, user) on an ad-hoc basis.
• Test the UI and API interfaces, and use the API to efficiently set up the UI tests.

TIP: Tip: For more information, see End-to-end testing Best Practices.

Determine if end-to-end tests are needed

Check the code coverage of a specific feature before writing end-to-end tests, for both GitLab Community Edition and GitLab Enterprise Edition projects. Does sufficient test coverage exist at the unit, feature, or integration levels? If you answered yes, then you don't need an end-to-end test.

For information about the distribution of tests per level in GitLab, see Testing Levels.

• See the How to test at the correct level? section of the Testing levels document.
• Review how often the feature changes. Stable features that don't change very often might not be worth covering with end-to-end tests if they are already covered in lower level tests.
• Finally, discuss the proposed test with the developer(s) involved in implementing the feature and the lower-level tests.

CAUTION: Caution: Check both GitLab Community Edition and GitLab Enterprise Edition coverage projects for previously-written tests for this feature. For analyzing the code coverage, you must understand which application files implement specific features.

In this tutorial we're writing a login end-to-end test, even though it has been sufficiently covered by lower-level testing, because it's the first step for most end-to-end flows, and is easiest to understand.

Identify the DevOps stage

The GitLab QA end-to-end tests are organized by the different stages in the DevOps lifecycle. Determine where the test should be placed by stage, determine which feature the test belongs to, and then place it in a subdirectory under the stage.

If the test is Enterprise Edition only, the test is created in the features/ee directory, but follow the same DevOps lifecycle format.

Create a skeleton test

In the first part of this tutorial we are testing login, which is owned by the Manage stage. Inside qa/specs/features/browser_ui/1_manage/login, create a file basic_login_spec.rb.

The outer context block

See the RSpec.describe outer block

CAUTION: Deprecation notice: The outer context was deprecated in 13.2 in adherence to RSpec 4.0 specifications. Use RSpec.describe instead.

The outer RSpec.describe block

Specs have an outer RSpec.describe indicating the DevOps stage.

# frozen_string_literal: true

module QA
  RSpec.describe 'Manage' do

  end
end

The describe block

Inside of our outer RSpec.describe, describe the feature to test. In this case, Login.

# frozen_string_literal: true

module QA
  RSpec.describe 'Manage' do
    describe 'Login' do

    end
  end
end