Merge branch 'improve-testing-documentation' into 'master'

Improve the testing documentation

Closes #29499 and #29623

See merge request !10161

doc/development/fe_guide/testing.md

@@ -13,10 +13,19 @@ 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
+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.
 
+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`](https://developer.mozilla.org/en-US/docs/Web/API/notification),
+which will have to be stubbed.
+
 ### Running frontend tests
 
 `rake karma` runs the frontend-only (JavaScript) tests.
@@ -80,24 +89,23 @@ 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
+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:
 
 ```ruby
-
 # For one spec
-it 'presents information about abuse report', js: true do
-    # assertions...
+it 'presents information about abuse report', :js 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
+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
 ```
 
@@ -113,13 +121,12 @@ 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"
-
+  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/