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

@@ -17,6 +17,15 @@ 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,18 +89,17 @@ 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
+it 'presents information about abuse report', :js do
   # assertions...
 end
 
-describe "Admin::AbuseReports", js: true do
+describe "Admin::AbuseReports", :js do
   it 'presents information about abuse report' do
     # assertions...
   end
@@ -119,7 +127,6 @@ Scenario: Developer can approve merge request
   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/