Frontend Testing

There are two types of tests you'll encounter while developing frontend code at GitLab. We use Karma and Jasmine for JavaScript unit testing, and RSpec feature tests with Capybara for integration testing.

Feature tests need to be written for all new features. Regression tests ought to be written for all bug fixes to prevent them from recurring in the future.

See the Testing Standards and Style Guidelines for more information on general testing practices at GitLab.

Karma test suite

GitLab uses the Karma test runner with Jasmine as its test framework for our JavaScript unit tests. For tests that rely on DOM manipulation, we generate HTML files using RSpec suites (see spec/javascripts/fixtures/*.rb for examples). Some fixtures are still HAML templates that are translated to HTML files using the same mechanism (see static_fixtures.rb). Those will be migrated over time. Fixtures are served during testing by the jasmine-jquery plugin.

JavaScript tests live in spec/javascripts/, matching the folder structure of app/assets/javascripts/: app/assets/javascripts/behaviors/autosize.js has a corresponding spec/javascripts/behaviors/autosize_spec.js file.

Keep in mind that in a CI environment, these tests are run in a headless browser and you will not have access to certain APIs, such as Notification, which will have to be stubbed.

Writing tests

Vue.js unit tests

See this section.

Running frontend tests

rake karma runs the frontend-only (JavaScript) tests. It consists of two subtasks:

rake karma:fixtures (re-)generates fixtures
rake karma:tests actually executes the tests

As long as the fixtures don't change, rake karma:tests (or yarn karma) is sufficient (and saves you some time).

Live testing and focused testing

While developing locally, it may be helpful to keep karma running so that you can get instant feedback on as you write tests and modify code. To do this you can start karma with npm run karma-start. It will compile the javascript assets and run a server at http://localhost:9876/ where it will automatically run the tests on any browser which connects to it. You can enter that url on multiple browsers at once to have it run the tests on each in parallel.

While karma is running, any changes you make will instantly trigger a recompile and retest of the entire test suite, so you can see instantly if you've broken a test with your changes. You can use jasmine focused or excluded tests (with fdescribe or xdescribe) to get karma to run only the tests you want while you're working on a specific feature, but make sure to remove these directives when you commit your code.

RSpec Feature Integration Tests

Information on setting up and running RSpec integration tests with Capybara can be found in the general testing guide.

Gotchas

Errors due to use of unsupported JavaScript features

Similar errors will be thrown if you're using JavaScript features not yet supported by the PhantomJS test runner which is used for both Karma and RSpec tests. We polyfill some JavaScript objects for older browsers, but some features are still unavailable:

Array.from
Array.first
Async functions
Generators
Array destructuring
For..Of
Symbol/Symbol.iterator
Spread

Until these are polyfilled appropriately, they should not be used. Please update this list with additional unsupported features.

RSpec errors due to JavaScript

By default RSpec unit tests will not run JavaScript in the headless browser and will simply rely on inspecting the HTML generated by rails.

If an integration test depends on JavaScript to run correctly, you need to make sure the spec is configured to enable JavaScript when the tests are run. If you don't do this you'll see vague error messages from the spec runner.

To enable a JavaScript driver in an rspec test, add :js to the individual spec or the context block containing multiple specs that need JavaScript enabled:

# For one spec
it 'presents information about abuse report', :js do
  # assertions...
end

describe "Admin::AbuseReports", :js do
  it 'presents information about abuse report' do
    # assertions...
  end
  it 'shows buttons for adding to abuse report' do
    # assertions...
  end
end

Spinach errors due to missing JavaScript

Note: Since we are discouraging the use of Spinach when writing new feature tests, you shouldn't ever need to use this. This information is kept available for legacy purposes only.

In Spinach, the JavaScript driver is enabled differently. In the *.feature file for the failing spec, add the @javascript flag above the Scenario:

@javascript
Scenario: Developer can approve merge request
  Given I am a "Shop" developer
  And I visit project "Shop" merge requests page
  And merge request 'Bug NS-04' must be approved
  And I click link "Bug NS-04"
  When I click link "Approve"
  Then I should see approved merge request "Bug NS-04"

5.4 KiB Raw Blame History