# @javarome/testscript

> Simple, straightforward TypeScript test solution

Latest version **0.13.1** (published 2024-10-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install @javarome/testscript
pnpm add @javarome/testscript
yarn add @javarome/testscript
bun add @javarome/testscript
```

Provides the command `testscript`.

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.13.1 |
| Published | 2024-10-21 |
| First published | 2023-10-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 234.9 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jérôme Beau |
| Maintainers | javarome |
| Keywords | test, unit-testing, typescript |

## Links

- npm: https://www.npmjs.com/package/@javarome/testscript
- Repository: https://github.com/Javarome/testscript
- Homepage: https://github.com/Javarome/testscript#readme
- Issues: https://github.com/Javarome/testscript/issues
- npm.io page: https://npm.io/package/@javarome/testscript

## Dependencies (1)

- [glob](https://npm.io/package/glob.md) ~10.3.10

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 0.13.1 (latest) — 2024-10-21
- 0.13.0 — 2024-10-20
- 0.12.1 — 2024-10-13
- 0.12.0 — 2024-10-13
- 0.11.2 — 2024-10-08
- 0.11.1 — 2024-10-08
- 0.11.0 — 2024-10-08
- 0.10.7 — 2023-11-21
- 0.10.6 — 2023-11-21
- 0.10.5 — 2023-11-20
- 0.8.5 — 2023-11-15
- 0.8.4 — 2023-11-15
- 0.8.3 — 2023-11-15
- 0.8.2 — 2023-11-15
- 0.8.1 — 2023-11-15
- … 16 more at https://npm.io/package/@javarome/testscript/versions

## README

# testscript

Tired of finding the right configuration to make Node + Common JS, ESM, Babel, Jest and TypeScript work together? \
Fed up of understanding why the configuration that used to work is not working anymore? \
Just want to run tests of your code, period? 

The alternative is here, as follows:

- Run all TypeScript stuff using [`tsx`](https://github.com/esbuild-kit/tsx) as a drop-in replacement for the `node` command. It just works with TypeScript, and it's fast.
- *A test is an autonomous executable*: you don't need a test runner to run a single test file. Instead, just execute the test file:
  ```
  tsx src/My.test.ts
  ````
  Thanks to Node's `assert()` predicates, this will throw a `TestError` if the test doesn't pass
  (this can also work with a `tsx` alternative as well, but `tsx` makes it easier).
- Keep syntax as similar as possible to the syntax used by [Jest](https://jestjs.io) (`describe()`, `test()`, `expect()`, `beforeEach()`...) , which is the most popular framework to test JS/TS.

```ts
// MyTest.ts
import { describe, expect, test } from '@javarome/testscript';

describe("Some software item", () => {

  test("does something", async () => {
    const item = new SoftwareItem('item1')
    expect(item.name).toBe("item1")
    expect(item.name).not.toBe("item2")
  })
})
```

- The only remaining thing you need is a [`TestRunner`](https://github.com/Javarome/testscript/blob/main/src/TestRunner.ts) to locate tests and execute them at once.
  One can be run using this command:

```
testscript
````

(make sure to install `tsx` before)

This will output:
![Test runner failure output](docs/TestRunner-success.png)
And an error will output as:

![Test runner failure output](docs/TestRunner-fail.png)

Of course this is typically what you want to run for your `test` npm script.

By default, it will look for all `*.test.ts` files in all subdirs, but you can specifiy a different file pattern, like:

```
testscript --include **/*.spec.ts
````

By default `node_modules` is ignored. You can also customize those excluded paths by specifying a second argument, which can be an array of paths:

```
testscript --include **/*.test.ts --exclude '{out/**,node_modules/**/*.*}'
```

You can also use the `TESTSCRIPT_INCLUDE` and `TESTSCRIPT_EXCLUDE` env vars.

## Assertions
The same assertions as found in Jest can be used:
- `x.toBe(y)` for `==` approximate comparison (string as number, nullish as other nullish, fasly as other falsy, etc.)
- `x.toEqual(y)` for strict `===`. Here the above comparisons will fail.
- `call.toThrow(errMsg)`
etc.

You can also insert the `not` operator, like in `x.not.toBe(y)`

## Lifecycle
The same callbacks can be used, like `beforeEach()`, etc.

## Options

A test can be skipped by setting the `skip` property in an option object before the test function parameter:
```ts
test("skipped test", {skip: true}, async () => {
  expect("not tested").toBe(true) // Will not be executed
})
```

## Reporting
By default, the `LogTestReporter` is used. See `bin/index.ts` to see how you could provide your own implementation of a `TestReporter`.

## Debugging

Once you have your test scripts ready in your `package.json`, all you need to need all or one test is to set your breakpoints in your tests
and run those scripts in debug mode.

Also note that the `TestRunner` uses a `DefaultLogger` instance as a `Logger`, which can be specified as its third constructor argument.
You can also set the `LOGLEVEL` env var to include `debug`.

---
_Source: https://npm.io/package/@javarome/testscript · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._