diff options
Diffstat (limited to 'doc/development/fe_guide/testing.md')
-rw-r--r-- | doc/development/fe_guide/testing.md | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/doc/development/fe_guide/testing.md b/doc/development/fe_guide/testing.md new file mode 100644 index 00000000000..bb6adeacc4c --- /dev/null +++ b/doc/development/fe_guide/testing.md @@ -0,0 +1,129 @@ +# 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](/doc/development/testing.md) +for more information on general testing practices at GitLab. + +## Karma test suite + +GitLab uses the [Karma][karma] test runner with [Jasmine][jasmine] as its test +framework for our JavaScript unit tests. For tests that rely on DOM +manipulation we use fixtures which are pre-compiled from HAML source files and +served during testing by the [jasmine-jquery][jasmine-jquery] plugin. + +### 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][jasmine-focus] 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][capybara] can be found in the +[general testing guide](/doc/development/testing.md). + +## 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: true` to the +individual spec or the context block containing multiple specs that need +JavaScript enabled: + +```ruby + +# For one spec +it 'presents information about abuse report', js: true do + # assertions... +end + +describe "Admin::AbuseReports", js: true 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" + +``` + +[capybara]: http://teamcapybara.github.io/capybara/ +[jasmine]: https://jasmine.github.io/ +[jasmine-focus]: https://jasmine.github.io/2.5/focused_specs.html +[jasmine-jquery]: https://github.com/velesin/jasmine-jquery +[karma]: http://karma-runner.github.io/ |