Upgrading to Jasmine 6.0

Overview

Most breaking changes in 6.0 result in errors that are hopefully self-explanatory. This guide will mainly cover changes that need special attention, either because the problems they cause are harder to detect or because the solution is less straightforward. Please see the release notes for a complete list of changes.

Contents

1. Preparation
   1. Updating code that spies on the mock clock
2. Upgrading jasmine-core
   1. If you use the jasmine package
   2. If you use jasmine-browser-runner
   3. If you use Karma
3. Updating your code for 6.0
   1. If you use Safari
   2. If you have duplicate spec/suite names
   3. Updating code that uses the eval form of setTimeout
   4. If you do custom spec filtering
   5. If you have a custom reporter
   6. If you use jsApiReporter
   7. If you have custom browser boot files
   8. If you run call boot() repeatedly in Node

Preparation

If you haven’t done so already, install jasmine-core 5.13 and resolve any errors or deprecation warnings.

Updating code that spies on the mock clock

Beginning with 6.0, Jasmine will throw an error if timing functions like setTimeout are spied on while the mock clock is installed. Prior to 6.0, that “worked” but prevented the mock clock from uninstalling itself correctly. If you have specs that combine the mock clock with spying on timing functions, you should update them as follows before upgrading to 6.0:

1. Identify any dependency on the mock clock leakage by disabling the specs that spy on mock clock timing functions with xit or xdescribe and making sure everything else passes. You can probably skip this step if all of your specs consistently pass without disabling randomization or specifying a random seed.
2. Modify the specs in question to either not use the mock clock or not spy on timing functions.

Upgrading jasmine-core

If you use the jasmine package

If you’re using the jasmine package, upgrade to version 6.0. This will also cause jasmine-core 6.0 to be installed.

If you use jasmine-browser-runner

If you’re using jasmine-browser-runner, upgrade to version 4.0. Your package manager (npm/yarn/etc) should automatically install jasmine-core 6.0 or later unless your package.json specifies an earlier version.

If you use Karma

Karma works with jasmine-core 6.0, although not all new features are available. Because Karma still depends on jasmine-core 4.x, you’ll need to use add an NPM override to your package.json file:

{
    // ...
    "overrides": {
        "karma-jasmine": {
            "jasmine-core": "^6.0.0"
        },
        "karma-jasmine-html-reporter": {
            "jasmine-core": "^6.0.0"
        }
    }
}

jasmine-core 7.0 will drop deprecated APIs that karma-jasmine 5.1 depends on. If you use Karma in a non-Angular context, consider migrating to a maintained alternative such as jasmine-browser-runner or web-test-runner. If you use Angular, please direct any questions about support for future versions of Jasmine to the Angular team.

Updating your code for 6.0

If you use Safari

Adding safariYieldStrategy: "time" to your configuration might significantly improve performance. This is an experimental setting that hasn’t yet been tested with a wide variety of test suites. Bug reports are appreciated.

If you have duplicate spec/suite names

By default, spec/suite names must be unique within a given parent suite. Jasmine will throw an error if it detects duplicates. If you want the old behavior of allowing duplicates, you can set the forbidDuplicateNames core configuration property to false.

Updating code that uses the eval form of setTimeout

The mock clock no longer supports the eval form of setTimeout and setInterval (e.g. setTimeout("alert('hi!')")). Any such code should be updated to pass a function rather than a string. Although the eval form is valid, it’s very rare in modern code, and there’s no way for the mock clock to properly support calls to it from strict and “sloppy” mode code.

If you do custom spec filtering

If you configure a spec filter, make sure it only uses spec properties that are part of the documented public API. Previous versions of Jasmine inadvertently exposed additional internal state to spec filters. Spec filters that rely on those properties will need to be updated.

Spec/suite orders that cause a suite to be entered more than once are no longer supported. This change only affects you if you pass a list of spec/suite IDs to Env#execute.

If you have a custom reporter

Several properties that were previously included in reporter events are now omitted:

• The expected and actual properties of expectation results. Use passed and message instead. expected and actual were never reliably available because not all objects are serializable.
• Meaningless properties of the suiteStarted and specStarted events, such as status and failedExpectations. That data is available from the suiteDone and specDone events.
• Undocumented properties of the order property of jasmineStarted and jasmineDone.

Arguments to reporter events are now deep cloned before being passed to each reporter. This protects reporters against later mutation by jasmine-core or by other reporters, but it might break reporters that manage state in unusual ways. If your reporter stores the arguments to specStarted or suiteStarted, make sure that it doesn’t rely on jasmine-core later mutating those objects. Spec and suite results should be obtained via the specDone and suiteDone events, not specStarted and suiteStarted.

This is also a good time to make sure that your reporter handles the failedExpectations properties of the suiteDone and jasmineDone events. Nothing about those errors as changed in 6.0, but ignoring them is a common bug in custom reporters, so it’s worth checking for.

If you use jsApiReporter

jsApiReporter is deprecated, and the browser boot files distributed with jasmine-core no longer install it. There are two ways to update code that uses it:

1. Recommended: Replace it with a custom reporter.
2. Call env.addReporter(jsApiReporter) before calling env.execute(). This will work until 7.0.

If you have custom browser boot files

6.0 introduces a new HtmlReporterV2 which offers a variety of improvements. You’ll automatically get the new reporter if you use jasmine-browser-runner, use the standalone distribution, or load boot files directly from jasmine-core. If you maintain your own custom boot files, they’ll need to be updated to use the new reporter. See the boot1.js that’s distributed with jasmine-core for a usage example. Note that HtmlReporterV2 creates different query string parameters than HtmlReporter, so any software that processes those parameters will also need to be updated.

Beginning with 6.0, the createElement and createTextNode options of the legacy HtmlReporter are ignored and may be removed. HtmlReporter will unconditionally use document.createElement and document.createTextNode. With that exception, existing browser boot files will continue to work through 6.x but will break in 7.0.

If you run call boot() repeatedly in Node

boot now defaults to creating a new core instance each time it’s called. If you call it multiple times and don’t pass an argument, you may want to pass false to retain the 5.x behavior.