6.0 roadmap

[sgravrock]

My current plan is to avoid doing a major release of jasmine-core for as long as possible. There are two reasons for that. One is that major releases come with a huge cost to the Jasmine ecosystem. Maintainers of related packages all have to update. Worse yet, many users (a majority, in my estimation) use Jasmine in combination with software that's either abandoned or irregularly maintained. Karma is the most obvious example right now, but it wasn't the first and it won't be the last. Major version bumps tend to leave users of those packages stranded on older version of jasmine-core.

The other reason is that Jasmine is mostly finished. That doesn't mean that there won't be any changes in the future. But I don't foresee anything that would require breaking changes. And since jasmine-core is largely insulated from the parts of the JS world that churn a lot, it'll hopefully be a long time before anything like that comes up.

That doesn't mean that there will never be a jasmine-core 6.0. But it does mean that there would need to be a really good reason, and right now I don't see any really good reason on the horizon.

That said, if we ever do a 6.0, there are a few things that would be nice to clean up:

• Remove the expected and actual properties of expectation and throwUnless results.
  These have never been accurate or reliably present due to JSON serialization limitations, and no reporters that use them have been found. They were deprecated in 5.4.0.
• Only load the first config file found.
• Revert to boot() always creating a new instance of jasmine-core.
  The change to reuse a core instance across multiple boot() calls was a mistake and it would be nice to undo it.
• Make the forbidDuplicateNames config option default to true.
• Consider decoupling the versioning of the jasmine and jasmine-core packages from each other. The peer dependency approach taken by jasmine-browser-runner seems to have worked out well.
  I'd almost certainly do this if I was in a situation where the jasmine package needed a breaking change but jasmine-core didn't. Otherwise, it might not be worthwhile.

[sgravrock]

Also:

• Drop support for the eval form of setTimeout in the mock clock. That would allow the entirety of jasmine-core to run in strict mode.
• Stop removing existing error and unhandled rejection listeners on startup when running in Node.
• Clean up any remaining code paths that pass browser error event handler arguments to user code.
• Look into whether Node's built-in fs.glob is a suitable replacement for the glob package.
• Prevent monkey patching by not exposing private APIs and by making everything that is exposed read-only. This might not be all that 6.0-specific: much of it could be done in a minor release, since private APIs are outside the scope of semver. On the other hand, anything that would irrevocably break zone.js probably can't be done even in a major release until zone.js becomes a lot less relevant than it is today. And anything that's known to break existing software ought to be delayed until a major release even if there are alternatives available.

[sgravrock]

Look into whether Node's built-in fs.glob is a suitable replacement for the glob package.

It isn't, and it won't be for years to come. Proper exclude support was only added in Node v22.14.0. And the pattern syntax is currently undocumented. (There is a PR open to add pattern documentation, but it appears stalled.) Either of those problems is, by itself, enough to rule out the use of fs.glob. We can revisit this once Node 22 reaches EOL.

[sgravrock]

It might also be wise to completely remove support for passing a spec order to Env#execute that interleaves suites with each other. That's been possible since v2.0.0.rc3, but it's disallowed if the suite whose execution is broken up calls beforeAll or afterAll. It causes multiple suiteStarted and suiteDone events to be emitted for the same suite, would probably come as a surprise to almost every reporter author. It's possible that TreeProcessor, which is one of the more challenging parts of the codebase to work with, could be dramatically simplified if that requirement was removed.

[sgravrock]

It would be nice to switch the HTML reporter's spec filtering functionality to do exact prefix matching (like --filter-path) rather than the current substring matching behavior. It's hard to do that as a non-breaking change because the filtering code lives in boot1.js. That makes the current query string parameters and their semantics de facto part of the public API.

[sgravrock]

This turned out to be doable without a breaking change.

[sgravrock]

The parameters passed to the suiteStarted, suiteDone, specStarted, and specDone are references to mutable internal state. This creates a couple of problems. First, a reporter that retains the parameters passed to suiteStarted or specStarted could behave differently when used with jasmine-browser-runner than when used with the jasmine package, because the former puts a serialization boundary between jasmine-core and reporters. Second, any change to the management of Spec or Suite internal state is directly observable by reporters and therefore arguably a breaking change. And some of the state management code, notably the stuff that updates spec statuses, is badly in need of change.

The next major release should switch to passing deep clones to reporter methods. That would also allow for dropping irrelevant properties like failedExpectations from the *Started methods, as well as documenting their parameters as having distinct, narrower types than the corresponding *Ended methods.

[sgravrock]

#826 as well

[sgravrock]

One is that major releases come with a huge cost to the Jasmine ecosystem. Maintainers of related packages all have to update. Worse yet, many users (a majority, in my estimation) use Jasmine in combination with software that's either abandoned or irregularly maintained. Karma is the most obvious example right now, but it wasn't the first and it won't be the last. Major version bumps tend to leave users of those packages stranded on older version of jasmine-core.

I think that what I said above was more or less right before the 5.0 release. But after taking another look at the ecosystem, I think things have changed. Today, just changing the version number isn't likely to have much impact. The real question is the effect of the underlying breaking changes.

I found the following packages that interoperate with Jasmine and have at least 50k weekly NPM downloads. 50k is a bit less than 1% of jasmine-core's download count and also the smallest download count of any package whose users I hear from, so it seems like a reasonable lower threshold for relevance.

Package	Weekly downloads	jasmine-core dep	Compatible with 5.x	Maintained	Notes
karma-jasmine	1.9m	^4.1.0	mostly, if NPM override used	no	Deprecated and de facto abandoned, but also part of the current Angular toolchain
karma-jasmine-html-reporter	2M	^4.0.0, ^5.0.0	yes	unknown	Wires up jasmine-core's HTML reporter. Hasn't needed any maintenance since jasmine-core 5.0.
jasmine-spec-reporter	865k	none	mostly	no
jasmine-reporters	196k	none	partially	no
jasmine-marbles	190k	none	probably	yes	Matchers. Also used with Jest.
testem	164k	none	partially	yes	Reporter. Also (perhaps mostly) used with other testing frameworks.
@wdio/jasmine-framework	50k	^5.0.0	partially	yes	Monkey patches jasmine-core, so even minor version compatibility is a crapshoot

(I'm considering a reporter to be partially compatible if it works with 5.x but fails to report some errors, and mostly compatible if it reports all errors but is missing support for some other features. I'm considering a package to be unmaintained if it's gone over a year with no maintainer activity and has open issues that are at least a year old and never received a maintainer response.)

That leaves only three significant packages that care about the version number itself. One of them, karma-jasmine, is abandoned. At this point I think it's safe to assume that any Karma user who hasn't already set up an NPM override to get the latest jasmine-core is going to stay on 4.x forever. So the impact of another major version bump by itself would be minimal. The relevant questions are:

• Which packages are actually broken by the changes?
• In the case of maintained packages, how difficult will the update be?
• In the case of unmaintained packages, do we care? I think the answer is clearly yes for karma-jasmine. Arguably it might be no for jasmine-reporters, given lower usage and existing compatibility problems.

A 6.0 that avoids breaking Karma or jasmine-spec-reporter could be a pretty reasonable thing to do, particularly if it's possible to clean up the reporter-related warts without breaking those packages. I think that's pretty likely.

[sgravrock]

selenium-webdriver 4.34 officially dropped support for Node 18. It appears to still work, but who knows how long that will continue. So there will probably come a time when the combination of Node 18, the latest browsers, and jasmine-browser-runner no longer works. Keeping Node 18 support until it actually breaks is an option, since I've long reserved the right to drop support for past-EOL problems in minor releases. But given that many people expect that sort of thing to be semver-major, it might be worth proactively dropping Node 18 if there's a major release.