ScripterI/O

Simple, fast, dependency-free ESM (ECMAScript Modules) test runner for JavaScript

Links

• Documentation
• Release Notes / History / Changes
• Contributing
• Issue Tracker
• NPM Package

---

Table of Contents

• Getting Started
  • Installation
  • Writing Tests
  • Running Tests
• Test Runner API
  • Assertions
  • Test Annotations
  • Context Options
• Async/Await Support
• Reporter
• HTTP Client
  • Request Methods

---

Demo

Getting started

Before you follow the steps below, make sure that you have:

Node.js installed globally only your system

Runner has JavaScript support only!

Runner has ESM support only!

Tested on: Node.js - v18, v20, v22, v23, v24

Installing

Install for Mac, Linux, or Windows:

npm install scripterio --save-dev
//or
yarn add scripterio --dev

Write your first test:

Use the test function to write test cases and the describe function to group them.

More examples:

• https://github.com/scripterio-js/scripterio-example (Unit, API, E2E tests)
• https://github.com/VadimNastoyashchy/json-mcp (Unit tests)

Let's start by creating the test.js test file:

Example↓

test.js

import { describe, test, expect} from 'scripterio'

describe('Unit tests:', () => {
  test('Array has correct length', () => {
    const arr = [1, 2, 3]
    expect(arr).toHaveLength(3)
  })
})

Run test:

Specify the --file= argument as the path to your test file

npx scripterio --file="test.js"
//or
yarn scripterio --file="test.js"

or

Specify the --folder= argument as the path to your test(s) folder

npx scripterio --folder="tests"
//or
yarn scripterio --folder="tests"

Test runner API

---

Option Name	Description
"test"	test is where you perform individual tests
"describe"	describe is for organizing and grouping tests. Describe can be nested in describe
"beforeEach"	Command allows to define setup tasks at the beginning of every It block
"afterEach"	Command allow to define teardown tasks at the end of every It block
"beforeAll"	Command allow to define setup tasks at the beginning of describe block
"afterAll"	Command allow to define teardown tasks at the end of describe block

---

Assertions

Use expect(actual_value) with assertions:

Example↓

  const arr = [1, 2, 3]
  expect(arr).toHaveLength(3)

---

Assert Name	Description
.toBeDefined()	Check actual value to be not undefined expect(1).toBeDefined()
.toHaveLength()	Check actual array length to have expected value expect(arr).toHaveLength(number)
.toBeFalsy()	Check actual value to be false
.toBeTruthy()	Check actual value to be true
.toBeEqual()	Check actual and expected values are the same (using ===) expect(value).toEqual(value)
.notToEqual()	Check actual and expected values are not the same (using ===) expect(value).notToEqual(value)
.toBeNull()	Check actual value to be null
.notToBeNull()	Check actual value to be not null
.toBeUndefined()	Check actual value to be undefined
.toBeNaN()	Check actual value to be NaN
.toBeGreaterThan()	Check actual value to be greater than expected value
.toBeLessThan()	Check actual value to be less than expected value
.toContain()	Use when you want to check that an item is in an array or a string.
.toMatch()	Use .toMatch() to check that a string matches a regular expression.

---

Test annotations

skip() Declares a skipped test or test group. Test/s is/are never run.

only() Declares an exclusive test or test group that will be executed. If used, all other tests are skipped.

todo() Declares a test or test group as "to-do." The test(s) is/are marked as pending and will not be executed. Helpful for planning and organizing future tests.

Example↓

test.skip('description', () => {})
//or
describe.skip('description', () => {})

test.only('description', () => {
  // Body of the only test that will be executed
})
//or
describe.only('description', () => {
  // Body of the only test group that will be executed
})

test.todo('description')
//or
describe.todo('description', () => {
  // This test group is a placeholder and won't run
})

---

Context options

Use {} as the second parameter for describe and test functions.

---

Option Name	Description
{ timeout: 2000 }	Option timeout (in ms) for specifying how long to wait before aborting.
	The default timeout is 5 seconds.
{ tags: 'smoke' }	To tag a test, either provide an additional details object
	when declaring a test.
	You can also tag all tests in a group or provide multiple tags:
	{ tags: ['smoke', 'regression'] }
{ retry: 2 }	To specify how many times a failed test should be retried
	before being marked as failed
	If a test fails, it will be retried up to the specified number of times
	If the test passes on any retry, it is marked as passed
	If it fails all attempts, it is marked as failed

Timeout example↓

To specify globally for all tests, use the following CLI flag:

npx scripterio --file="test.js" --timeout=30000
# or
npx scripterio --folder="tests" --timeout=20_000

To specify individual tests, use the context option:

test('Wait 1 sec and check', { timeout: 2000}, async () => {
  const number = await new Promise((resolve) =>
    setTimeout(() => resolve(1), 1_000)
  )
  expect(number).toBeDefined()
})

Tags example↓

Single tag:

describe('Unit tests:', () => {
  test('Array has correct length', { tags: 'smoke' }, () => {
    const arr = [1, 2, 3]
    expect(arr).toHaveLength(3)
  })
})

You can now run tests that have a particular tag with --tags command line option:

npx scripterio --folder="tests" --tags="smoke"

Multiple tags:

describe('Unit tests:', () => {
  test('Array has correct length', { tags: ['smoke', 'regression'] }, () => {
    const arr = [1, 2, 3]
    expect(arr).toHaveLength(3)
  })
})

You can now run tests that have tags separated by , (comma) with --tags command line option:

npx scripterio --folder="tests" --tags="smoke,regression"

Retry example↓

To specify globally for all tests, use the following CLI flag:

npx scripterio --file="test.js" --retry=2
# or
npx scripterio --folder="tests" --retry=3

To specify individual tests, use the context option:

test('Flaky test', { retry: 2 }, () => {
  // Your test code that might fail intermittently
})

This will retry the test up to 2 additional times if it fails.

---

Async/Await support

Also supports async/await approach. To use it, just add async keyword before the function callback inside the test block:

Example↓

test('Wait 1 sec and check', async () => {
  const number = await new Promise((resolve) =>
    setTimeout(() => resolve(1), 1_000)
  )
  expect(number).toBeDefined()
})

Reporter

ScripterI/O provides test reporting functionality with multiple reporter options:

HTML Reporter

To generate an HTML report of your test results, use the --reporter=html flag:

npx scripterio --file=test.js --reporter=html

This will create a detailed HTML report in the scripterio-report directory. The report includes:

• Total test count, passed tests, and failed tests
• Organized test results by file and test suites
• Detailed error information for failed tests
• Interactive UI to expand/collapse test suites

Example of HTML reporter:

HTTP client

ScripterI/O has built-in http client to preform the request.

Example↓

test.js

import { describe, test, expect, request} from 'scripterio'

describe('Example of http client', () => {
  test('Demonstrate get() method to get single object', async () => {
    const response = await request.get('https://api.restful-api.dev/objects/7')
    expect(response.status).toBeEqual(200)
  })
})

If you use the request object in your tests, the network details are automatically displayed in the HTML report!

Request methods

---

Option Name	Description
request.get()	Sends a GET request to the specified URL and returns a Response object.
request.post()	Sends a POST request to the specified URL
request.put()	Sends a PUT request to the specified URL
request.patch()	Sends a PATCH request to the specified URL
request.delete()	Sends a DELETE request to the specified URL

Additional examples : https://github.com/scripterio-js/scripterio-example/blob/main/tests/api_tests.j