A fast JavaScript test framework, for browser apps, NPM packages, and Node.js scripts.
import {test, expect, is} from "@benchristel/taste"
test("greet", {
"greets the world"() {
expect(greet("world"), is, "Hello, world!")
},
"defaults to a generic greeting"() {
expect(greet(null), is, "Hello, you person, you!")
},
})
function greet(name) {
return `Hello, ${name || "you person, you"}!`
}Taste's own tests are written using Taste. You can run the tests in your browser here.
https://benchristel.github.io/try-taste/
There is also a set of downloadable koans/tutorials that walk you through Taste's features from basic to advanced, and serve as a reference for how to integrate Taste into a project.
// copy-paste this into test.mjs
import {test, expect, is} from "@benchristel/taste"
import {getAllTests, runTests, formatTestResultsAsText} from "@benchristel/taste"
// add a test to the global suite
test("my first Taste test", {
"runs"() {
expect(1 + 1, is, 2)
},
})
// run the tests and print the results
runTests(getAllTests())
.then(formatTestResultsAsText)
.then(console.log)Then run time node test.mjs. Replace node with bun to go even faster!
- Preact + TypeScript + Vite + Taste (recommended)
- React + Flow + Snowpack + Taste (deprecated)
yarn add @benchristel/taste
- Tests can run in the browser. You can integrate test results into the dev UI of your app!
- Tests can live in the same files as production code. Or you can use any other organization scheme. The tests are automatically stripped out of production builds of your app.
- The tests are fast—up to 50x faster than Jest tests. Taste can run tens of thousands of tests per second.
- Custom matchers couldn't be simpler. Any function that returns a boolean can be used in a test assertion. Test failures still get pretty-formatted as you'd expect.
asynctests are not run in parallel. Thus, if youawaita 100ms timer in a test, your suite will take 100ms longer to run. It's up to you to design your code so promises can resolve quickly in tests. The ideal is to resolve all promises in microtasks, which will allow your async tests to run as fast as synchronous code.- By default, there is no timeout for
asynctests. If you accidentallyawaita promise that never resolves, your tests will hang with no indication of what's wrong. Reduce the pain of this eventuality by running your tests on every code change so you can quickly revert mistakes. You can add timeouts to your test suite with @benchristel/taste-timeout. - There are no equivalents of Jest's
beforeEachetc., nor are there nesteddescribeorcontextblocks. You can de-duplicate repeated setup by simply extracting functions and calling them, as you would for duplicated production code. In my experience, this makes for more readable tests in the long run. However, Taste is flexible enough that you could build your own Jest-like test-definition syntax on top of it, if you wanted to. - Taste has no facilities for mocking. It's clearer, and easy enough, to roll your own test doubles if you need to. Or use another mocking library; there are plenty to choose from.
- Add Snowpack for auto-refresh, and you can get near-instantaneous test feedback whenever you change a JavaScript file.
- To run tests in CI or as a pre-push hook, you can set up Puppeteer, which runs the tests in a headless Chrome browser. That might sound like a lot of overhead, but it's still slightly faster than using Jest (1.2s vs. 1.3s startup time on my machine).
import {
test,
expect,
is,
equals,
not,
which,
} from "@benchristel/taste"
The test method is the usual way of writing tests in
Taste. The TestDefinitions type is a map of strings
(test scenario names) to test functions:
type TestDefinitions = {
[scenario: string]: () => void | Promise<void>,
}Typical usage looks like this:
import {test, expect, is} from "@benchristel/taste"
test("a Counter", {
"starts at zero"() {
const c = new Counter()
expect(c.value(), is, 0)
},
"increments once"() {
const c = new Counter()
c.increment()
expect(c.value(), is, 1)
},
})When the test results are formatted using Taste's built-in
formatter (formatTestResultsAsText), the subject name
and scenario name will be concatenated for each test. So
in the above example, you'd see failure messages like:
a Counter increments once
expect(
0,
is,
1
)
Throws an error if the given predicate returns a falsey
value when passed the expected and actual values.
Note that the subject is passed as the last argument
to the predicate function. This is to accommodate predicates
that are designed to be curried.
Here's an example of how you might define a custom
isGreaterThan predicate:
import {test, expect, is} from "@benchristel/taste"
function isGreaterThan(reference, n) {
return n > reference
}
test("rolling a die", {
"produces a positive number"() {
expect(rollDie(), isGreaterThan, 0)
},
})Returns whether its arguments are ===.
is is curried, so the following are equivalent:
expect(1 + 1, is, 2)
expect(1 + 1, is(2))Returns whether two objects are deeply equal. The rules for comparison are complicated, but work similarly to the ones in Jest, Jasmine, and other test frameworks you might be familiar with. For examples of behavior, see the tests.
equals({a: 1}, {a: 1}) // true
equals({a: 1}, {a: 2}) // falseequals is curried, so the following are equivalent:
expect(1 + 1, equals, 2)
expect(1 + 1, equals(2))Returns a negated version of the given predicate p; i.e.
not(p) returns true for some arguments iff p returns
falsey for those arguments.
The following are equivalent:
expect(2 + 2, not(is), 5)
expect(2 + 2, not(is(5)))
Returns a curried version of the given function.
Partially-applied functions generated from the curried
function will be pretty-printed by
formatTestResultsAsText in a format that includes the
given name.
Given a predicate, returns a magical object that equals
any value for which the predicate returns truthy. You can
use which to customize how objects should be compared when
using equals—usually to relax some constraint.
const isBetween = curry((min, max, n) => {
return n >= min && n <= max
}, "isBetween")
test("randomDndCharacter", {
"generates reasonable ability scores"() {
expect(randomDndCharacter(), equals, {
str: which(isBetween(7, 18)),
dex: which(isBetween(7, 18)),
con: which(isBetween(7, 18)),
int: which(isBetween(7, 18)),
wis: which(isBetween(7, 18)),
cha: which(isBetween(7, 18)),
})
},
})import {
getAllTests,
runTests,
formatTestResultsAsText,
} from "@benchristel/taste"
Returns all tests that have been registered via test().
Nilpotent, but may return different results on subsequent
calls if there are intervening calls to test().
Runs tests asynchronously and returns their results as a machine-readable object.
Formats test results from runTests as a human-readable
string.
Taste works with Snowpack with no special configuration.
I recommend bundling your code for production with
@snowpack/plugin-webpack. This will automatically remove
any taste tests from your production build.
Non-Taste-specific note: if you use snowpack+webpack, do not
put any JavaScript
directly in your index.html; as of this writing, the
webpack plugin will not build it correctly and it will not
be run in the bundled version of your site. Instead, do
something like this to include your root index.js module:
<script type="module" src="./index.js"></script>Taste works great with Vite! I recommend it.
To ensure your tests run automatically and you do not see duplicate test results when components get hot-reloaded, I recommend turning hot module replacement (HMR) off for files that contain tests. You can do that like this:
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [react({include: ["**/*.impl.js", "**/*.impl.jsx"]})],
build: {
target: "chrome91",
},
})Using this config, you'd place all of your non-test code
in *.impl.js or *.impl.jsx files, and only those files
would get hot-reloaded. An alternative would be to use
something like exclude: ["**/*.test.js"] if you use that
naming convention.
If you're using Webpack, Rollup, or most other module
bundlers, you shouldn't have to do anything special to
remove Taste tests from the production build of your app.
If you find that tests are showing up in bundled code,
ensure that process.env.NODE_ENV === "production" and your
optimizer is configured for tree-shaking / dead code
elimination.
This section contains instructions for working on Taste itself.
Fast test runner:
yarn dev
open http://localhost:8080
Robot-friendly test runner:
yarn test