diff options
Diffstat (limited to 'doc/development/testing_guide/frontend_testing.md')
| -rw-r--r-- | doc/development/testing_guide/frontend_testing.md | 148 |
1 files changed, 104 insertions, 44 deletions
diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 0c63f51cb45..0d0d511582b 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -62,6 +62,7 @@ describe('.methodName', () => { }); }); ``` + #### Testing promises When testing Promises you should always make sure that the test is asynchronous and rejections are handled. @@ -69,9 +70,9 @@ Your Promise chain should therefore end with a call of the `done` callback and ` ```javascript // Good -it('tests a promise', (done) => { +it('tests a promise', done => { promise - .then((data) => { + .then(data => { expect(data).toBe(asExpected); }) .then(done) @@ -79,10 +80,10 @@ it('tests a promise', (done) => { }); // Good -it('tests a promise rejection', (done) => { +it('tests a promise rejection', done => { promise .then(done.fail) - .catch((error) => { + .catch(error => { expect(error).toBe(expectedError); }) .then(done) @@ -91,48 +92,85 @@ it('tests a promise rejection', (done) => { // Bad (missing done callback) it('tests a promise', () => { - promise - .then((data) => { - expect(data).toBe(asExpected); - }) + promise.then(data => { + expect(data).toBe(asExpected); + }); }); // Bad (missing catch) -it('tests a promise', (done) => { +it('tests a promise', done => { promise - .then((data) => { + .then(data => { expect(data).toBe(asExpected); }) - .then(done) + .then(done); }); // Bad (use done.fail in asynchronous tests) -it('tests a promise', (done) => { +it('tests a promise', done => { promise - .then((data) => { + .then(data => { expect(data).toBe(asExpected); }) .then(done) - .catch(fail) + .catch(fail); }); // Bad (missing catch) -it('tests a promise rejection', (done) => { +it('tests a promise rejection', done => { promise - .catch((error) => { + .catch(error => { expect(error).toBe(expectedError); }) - .then(done) + .then(done); }); ``` -#### Stubbing +#### Stubbing and Mocking + +Jasmine provides useful helpers `spyOn`, `spyOnProperty`, `jasmine.createSpy`, +and `jasmine.createSpyObject` to 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 alter `window.location`). The +documentation for these methods can be found in the [jasmine introduction page](https://jasmine.github.io/2.0/introduction.html#section-Spies). + +Sometimes you may need to spy on a method that is directly imported by another +module. GitLab has a custom `spyOnDependency` method which utilizes +[babel-plugin-rewire](https://github.com/speedskater/babel-plugin-rewire) to +achieve this. It can be used like so: + +```javascript +// my_module.js +import { visitUrl } from '~/lib/utils/url_utility'; + +export default function doSomething() { + visitUrl('/foo/bar'); +} -For unit tests, you should stub methods that are unrelated to the current unit you are testing. -If you need to use a prototype method, instantiate an instance of the class and call it there instead of mocking the instance completely. +// my_module_spec.js +import doSomething from '~/my_module'; -For integration tests, you should stub methods that will effect the stability of the test if they -execute their original behaviour. i.e. Network requests. +describe('my_module', () => { + it('does something', () => { + const visitUrl = spyOnDependency(doSomething, 'visitUrl'); + + doSomething(); + expect(visitUrl).toHaveBeenCalledWith('/foo/bar'); + }); +}); +``` + +Unlike `spyOn`, `spyOnDependency` expects 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 on +[its repository Readme doc](https://github.com/speedskater/babel-plugin-rewire#babel-plugin-rewire). ### Vue.js unit tests @@ -143,8 +181,8 @@ See this [section][vue-test]. `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 +* `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). @@ -152,19 +190,41 @@ 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 +can get instant feedback on as you write tests and modify code. To do this +you can start karma with `yarn 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 +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 +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. +It is also possible to only run karma on specific folders or files by filtering +the run tests via the argument `--filter-spec` or short `-f`: + +```bash +# Run all files +yarn karma-start +# Run specific spec files +yarn karma-start --filter-spec profile/account/components/update_username_spec.js +# Run specific spec folder +yarn karma-start --filter-spec profile/account/components/ +# Run all specs which path contain vue_shared or vie +yarn karma-start -f vue_shared -f vue_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: + +```bash +# Run all specs named `file_spec` within the IDE subdirectory +yarn karma -f 'spec/javascripts/ide/**/file_spec.js' +``` + ## RSpec feature integration tests Information on setting up and running RSpec integration tests with @@ -176,19 +236,19 @@ Information on setting up and running RSpec integration tests with 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 +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 +* 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 +Until these are polyfilled appropriately, they should not be used. Please update this list with additional unsupported features. ### RSpec errors due to JavaScript @@ -223,7 +283,7 @@ end ### 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 +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` @@ -243,11 +303,11 @@ Scenario: Developer can approve merge request [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/ -[vue-test]:https://docs.gitlab.com/ce/development/fe_guide/vue.html#testing-vue-components -[RSpec]: https://github.com/rspec/rspec-rails#feature-specs -[Capybara]: https://github.com/teamcapybara/capybara -[Karma]: http://karma-runner.github.io/ -[Jasmine]: https://jasmine.github.io/ +[vue-test]: https://docs.gitlab.com/ce/development/fe_guide/vue.html#testing-vue-components +[rspec]: https://github.com/rspec/rspec-rails#feature-specs +[capybara]: https://github.com/teamcapybara/capybara +[karma]: http://karma-runner.github.io/ +[jasmine]: https://jasmine.github.io/ --- |