Skip to content

Frontend testing standards and style guidelines

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

Unit and feature tests need to be written for all new features. Most of the time, you should useRSpecfor your feature tests.

Regression tests should be written for bug fixes to prevent them from recurring in the future.

See the测试标准和风格指南page for more information on general testing practices at GitLab.

Karma test suite

GitLab uses theKarmatest runner withJasmineas its test framework for our JavaScript unit and integration tests. For integration tests, we generate HTML files using RSpec (seespec/javascripts/fixtures/*.rbfor examples). Some fixtures are still HAML templates that are translated to HTML files using the same mechanism (seestatic_fixtures.rb). Adding these static fixtures should be avoided as they are harder to keep up to date with real views. The existing static fixtures will be migrated over time. Please seegitlab-org/gitlab-ce#24753to track our progress. Fixtures are served during testing by thejasmine-jqueryplugin.

JavaScript tests live inspec/javascripts/, matching the folder structure ofapp/assets/javascripts/:app/assets/javascripts/behaviors/autosize.jshas a correspondingspec/javascripts/behaviors/autosize_spec.jsfile.

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 asNotification, which will have to be stubbed.

Best practices

Naming unit tests

When writing describe test blocks to test specific functions/methods, please use the method name as the describe block name.

// Gooddescribe('methodName',()=>{it('passes',()=>{expect(true).toEqual(true);});});// Baddescribe('#methodName',()=>{it('passes',()=>{expect(true).toEqual(true);});});// Baddescribe('.methodName',()=>{it('passes',()=>{expect(true).toEqual(true);});});

Testing promises

When testing Promises you should always make sure that the test is asynchronous and rejections are handled. Your Promise chain should therefore end with a call of thedonecallback anddone.failin case an error occurred.

// Goodit('tests a promise',done=>{promise.then(data=>{expect(data).toBe(asExpected);}).then(done).catch(done.fail);});// Goodit('tests a promise rejection',done=>{promise.then(done.fail).catch(error=>{expect(error).toBe(expectedError);}).then(done).catch(done.fail);});// Bad (missing done callback)it('tests a promise',()=>{promise.then(data=>{expect(data).toBe(asExpected);});});// Bad (missing catch)it('tests a promise',done=>{promise.then(data=>{expect(data).toBe(asExpected);}).then(done);});// Bad (use done.fail in asynchronous tests)it('tests a promise',done=>{promise.then(data=>{expect(data).toBe(asExpected);}).then(done).catch(fail);});// Bad (missing catch)it('tests a promise rejection',done=>{promise.catch(error=>{expect(error).toBe(expectedError);}).then(done);});

Stubbing and Mocking

Jasmine provides useful helpersspyOn,spyOnProperty,jasmine.createSpy, andjasmine.createSpyObjectto facilitate replacing methods with dummy placeholders, and recalling when they are called and the arguments that are passed to them. These tools should be used liberally, to test for expected behavior, to mock responses, and to block unwanted side effects (such as a method that would generate a network request or alterwindow.location). The documentation for these methods can be found in thejasmine introduction page.

Sometimes you may need to spy on a method that is directly imported by another module. GitLab has a customspyOnDependencymethod which utilizesbabel-plugin-rewireto achieve this. It can be used like so:

// my_module.jsimport{visitUrl}from'~/lib/utils/url_utility';exportdefaultfunctiondoSomething(){visitUrl('/foo/bar');}// my_module_spec.jsimportdoSomethingfrom'~/my_module';describe('my_module',()=>{it('does something',()=>{constvisitUrl=spyOnDependency(doSomething,'visitUrl');doSomething();expect(visitUrl).toHaveBeenCalledWith('/foo/bar');});});

UnlikespyOn,spyOnDependencyexpects its first parameter to be the default export of a module who's import you want to stub, rather than an object which contains a method you wish to stub (if the module does not have a default export, one is be generated by the babel plugin). The second parameter is the name of the import you wish to change. The result of the function is a Spy object which can be treated like any other jasmine spy object.

Further documentation on the babel rewire pluign API can be found onits repository Readme doc.

Vue.js unit tests

See thissection.

Running frontend tests

rake karma运行frontend-only (JavaScript)测试。它缺点ists of two subtasks:

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

As long as the fixtures don't change,rake karma:tests(oryarn 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 withyarn run karma-start. It will compile the javascript assets and run a server athttp://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 usejasmine focusedor excluded tests (withfdescribeorxdescribe) 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.

It is also possible to only run karma on specific folders or files by filtering the run tests via the argument--filter-specor short-f:

# Run all filesyarn karma-start# Run specific spec filesyarn karma-start--filter-specprofile/account/components/update_username_spec.js# Run specific spec folderyarn karma-start--filter-specprofile/account/components/# Run all specs which path contain vue_shared or vieyarn karma-start-fvue_shared-fvue_mr_widget

You can also use glob syntax to match files. Remember to put quotes around the glob otherwise your shell may split it into multiple arguments:

# Run all specs named `file_spec` within the IDE subdirectoryyarn karma-f'spec/javascripts/ide/**/file_spec.js'

RSpec feature integration tests

Information on setting up and running RSpec integration tests withCapybaracan be found in theTesting Best Practices.

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 anrspectest, add:js在的dividual spec or the context block containing multiple specs that need JavaScript enabled:

# For one specit'presents information about abuse report',:jsdo# assertions...enddescribe"Admin::AbuseReports",:jsdoit'presents information about abuse report'do# assertions...endit'shows buttons for adding to abuse report'do# assertions...endend

Spinach errors due to missing JavaScript

NOTE: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*.featurefile for the failing spec, add the@javascriptflag above the Scenario:

@javascriptScenario: Developer can approve merge requestGiven I am a "Shop" developerAnd I visit project "Shop" merge requests pageAnd merge request 'Bug NS-04' must be approvedAnd I click link "Bug NS-04"When I click link "Approve"Then I should see approved merge request "Bug NS-04"

Return to Testing documentation

Baidu
map