Skip to content

First pre-release for v3

Pre-release
Pre-release
Compare
Choose a tag to compare
@thetutlage thetutlage released this 27 Jun 10:04
· 75 commits to develop since this release
v3.0.0-0
eea1270

Here you go 🎉

This release will unblock us and allow to migrate existing plugins to work with v3. Feel free to give it a try and report bugs (if you find any).

npm i -D @japa/runner@next

Breaking changes

  • Codebase is ESM only
  • Removed —ignore-tags CLI flag. Instead, you can negate tags by prefixing them with a tilde.
- node bin/test.js --ignore-tags="@slow"
+ node bin/test.js --tags="~@slow"
  • The behavior of the processCliArgs method has been changed completely.
    • Earlier, the method returned a config object by parsing the CLI arguments. Now this method returns undefined
    • Instead, this method will process the command line arguments, and Japa internally will merge these arguments with the user-supplied config object.
- import { configure, processCliArgs } from '@japa/runner'
- configure({
-   ...processCliArgs(process.argv.splice(2)),
-   {
-      //user-defined config
-   }
- })

+ import { configure, processCLIArgs } from '@japa/runner'
+
+ processCLIArgs(process.argv.splice(2))
+ configure({
+   {
+      //user-defined config
+   }
+ })
  • The config.reporters property has been changed from an array to an object. The object has two properties, i.e., activated and list.
    • After this change, you can register multiple reporters inside your config file, but they will not be activated by default.
    • You must add their names to the activated array to activate them.
    • Or, by using the --reporters CLI flag.
configure({
-   reporters: [spec()]
+   reporters: {
+     activated: ['spec'],
+     list: [spec()]
+   }
})
  • Removed the TestContext.created method. This method was added quickly to facilitate the @japa/browser-client plugin. Instead, you can use the japa.getActiveTest() to get an instance of the active test and then use its context for reading properties. Feel free to ping me if you use this method and need clarification on its removal.
  • The PluginFn signature has been changed.
type PluginFn = (
-  config: Required<Config>,
-  runner: Runner,
-  classes: {
-    Test: typeof Test
-    TestContext: typeof TestContext
-    Group: typeof Group
-  }
+ japa: {
+   config: Required<Config>
+   cliArgs: CLIArgs
+   runner: Runner
+   emitter: Emitter
+ }
) => void | Promise<void>

If you notice, the plugin does not receive the core classes. You can import them directly from the @japa/runner/core submodule.

import { Test, TestContext, Group } from '@japa/runner/core'
  • All types are exported from the @japa/runner/types submodule.
  • The config.importer method now receives an instance of the URL class. Earlier, it used to be an absolute file path. Ideally, you can remove the importer implementation from your config file if it just converted the path to the URL.

Package removed

We have moved a lot of stuff within the @japa/runner codebase; hence, the following packages will be removed post-v3 release. These packages are not compatible with @japa/runner@3.

  • @japa/spec-reporter : Uninstall the package and remove its usage from the config file. Japa will register the spec reporter by default.
  • @japa/dot-reporter: Same as the @japa/spec-reporter. Remove its usage from the config file and uninstall the package.
  • @japa/run-failed-tests: The plugin has been removed. Instead, you must run failed tests using the new --retry flag.
  • @japa/base-reporter: The base reporter was used to create custom reporters by extending the BaseReporter class. This class has been moved within the Runner codebase, and you can import it as follows.
import { BaseReporter } from '@japa/runner/core'
export class MyReporter extends BaseReporter {}
  • @japa/synthetic-events : The package was used to emit fake events that can be used to create a custom reporter. You cannot need this package anymore. Instead, use the runner factory to test reporters.

Features

  • Introduce the --retry flag to run tests that failed from the previous run. No config changes are needed for this. Just use the CLI flag.
  • Introduce the —-retries flag to define the number of times a test should be retried after failure. The flag applies to all the tests that do not set an explicit retries count.
  • Add ndjson reporter. Julien needs it for the VSCode extension. Its output might change in the future as we start the editor integration.
  • Add the test.throws method. It can be used to write an assertion that the test fails at the top level. Consider this example:
// BEFORE
test('disallow duplicate emails', async ({ assert }) => {
  await User.create({ email: 'foo@bar.com' })

  try {
    await User.create({ email: 'foo@bar.com' })
  } catch (error) {
    assert.equal(error.message, 'Unique constraint failure')
  }
})
// AFTER
test('disallow duplicate emails', async () => {
  await User.create({ email: 'foo@bar.com' })
  await User.create({ email: 'foo@bar.com' })
})
  .throws('Unique constraint failure')
  • Introduce SummaryBuilder that reporters and plugins can access from the runner object. The summary builder allows registering functions that can return a key-value pair to display inside the test summary output.
runner.summaryBuilder.use(() => {
  return [
    {
      key: 'Node.js version',
      value: process.version
    }
  ]
})

Handling uncaught errors differently

Earlier, Japa used to try and associate uncaughtExceptions with the test that might have triggered it. This behavior was tricky and usually produced many false positives.

Also, we collected all the uncaughtExceptions until the process exits and displayed their count inside the tests runner summary output.

In Japa@3, the above defined behaviors have been removed with a simple implementation. Now Japa listens for uncaughtExceptions and uncaughtRejections globally and reports them as they occur. They are not aggregated in the output summary.

This change has no impact on the way you write tests.

Better errors output

Inspired by Vitest, we now display red borders around individual errors with a paging counter. The border makes it easy to scan errors when you have a massive list of them. You can easily see where an error starts and ends.

Old output

japa_errors_old_output_min

New Output

japa_errors_new_output_min

Commits

  • fix: set default retries to 0 3468e98
  • feat: use core summary builder for printing summary 2a197d1
  • test: fix failing tests 2680d61
  • chore: update dependencies 62279e0
  • refactor: final cosmetic tweaks 69c044c
  • feat: add test.throws method c028dd6
  • feat: add retry plugin for retrying failed tests b82ca2e
  • feat: add ndjson reporter a1c595f
  • feat: add dot reporter 0aeb741
  • test: update factory to add another failing variation 73720f3
  • feat: add tests factory and example for spec reporter 1dc3fba
  • chore: update dependencies f4415b4
  • feat: add spec reporter eedd814
  • feat: add base reporter and re-arrange core exports e8eefbb
  • chore: remove cliui dependency and use colors instead 286390a
  • refactor: remove resource method in favor of getActiveTest 8b7e935
  • feat: add resource method to create test aware resources f35c6f9
  • feat: refactor internals c57d344
  • chore: migrate structure to ESM 12ce5d7
  • refactor: make --files filter to match without using .spec keyword f8458f3
  • docs: update License file 8db4cf9
  • chore: update dependencies 6c4f3be
  • feat: export Emitter and Refiner 67bbd06
  • chore: update dependencies d18b8e2

v2.5.1...v3.0.0-0

Full Changelog: v2.5.1...v3.0.0-0

Assets 2