{"id":20052212,"url":"https://github.com/sondr3/minitest","last_synced_at":"2025-05-05T11:32:16.542Z","repository":{"id":39627021,"uuid":"443854860","full_name":"sondr3/minitest","owner":"sondr3","description":"A low-feature, dependency-free and performant test runner inspired by Rust and Deno","archived":false,"fork":false,"pushed_at":"2025-02-07T16:41:56.000Z","size":105,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-23T20:07:20.623Z","etag":null,"topics":["test","test-runner","testing","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sondr3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-02T19:41:33.000Z","updated_at":"2025-02-07T16:41:59.000Z","dependencies_parsed_at":"2023-02-09T23:15:15.095Z","dependency_job_id":"b6f37c65-f057-40e2-b535-2d45bb4b35dd","html_url":"https://github.com/sondr3/minitest","commit_stats":{"total_commits":67,"total_committers":2,"mean_commits":33.5,"dds":"0.11940298507462688","last_synced_commit":"99dacb5800589969a9e9f8a7b9f3758e99485fb9"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sondr3%2Fminitest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sondr3%2Fminitest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sondr3%2Fminitest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sondr3%2Fminitest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sondr3","download_url":"https://codeload.github.com/sondr3/minitest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252489170,"owners_count":21756279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["test","test-runner","testing","typescript"],"created_at":"2024-11-13T12:16:26.076Z","updated_at":"2025-05-05T11:32:16.067Z","avatar_url":"https://github.com/sondr3.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eminitest\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/sondr3/minitest/actions\"\u003e\u003cimg alt=\"GitHub Actions Status\" src=\"https://github.com/sondr3/minitest/workflows/pipeline/badge.svg\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@sondr3/minitest\"\u003e\u003cimg alt=\"NPM\" src=\"https://img.shields.io/npm/v/@sondr3/minitest\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cb\u003eA low-feature, dependency-free and performant test runner inspired by Rust and Deno\u003c/b\u003e\n\u003c/p\u003e\n\n- **Simplicity**: Use the `mt` test runner with the `test` function, nothing more.\n- **Performance**: By doing and including less we can run more quick.\n- **Minimal**: Bring your own assertions, snapshots, `mt` will always be dependency free.\n\n\u003cdetails\u003e\n\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\u003cbr /\u003e\n\n## Table of Contents\n\n- [Quickstart](#quickstart)\n- [Usage](#usage)\n  - [Finding tests](#finding-tests)\n  - [Writing tests](#writing-tests)\n  - [Running tests](#running-tests)\n  - [Filtering](#filtering)\n  - [Failing fast](#failing-fast)\n  - [Quiet](#quiet)\n  - [CLI](#cli)\n- [Extras](#extras)\n  - [TypeScript](#typescript)\n  - [Coverage](#coverage)\n  - [JSX, TSX, browsers](#jsx-tsx-browsers)\n- [Rationale](#rationale)\n- [License](#license)\n\u003c/details\u003e\n\n# Quickstart\n\n1. Install via your tool of choice: `pnpm add --dev @sondr3/minitest`\n2. Add a test script to `package.json`:\n\n   ```json\n     \"scripts\": {\n       \"test\": \"mt \u003cdir\u003e\",\n     },\n   ```\n\n3. Write your tests:\n\n   ```js\n   import { strict as assert } from \"assert\";\n   import { test } from \"@sondr3/minitest\";\n\n   test(\"it works!\", () =\u003e {\n     assert(true === true, \"Phew\");\n   });\n   ```\n\n4. Run your tests: `pnpm test`\n\n   ```text\n   running 1 test\n   running 1 test in dir/index.test.js\n   test  it works! ... ok\n\n   test result: ok. 1 passed; 0 failed; 0 ignored; 0 filtered out; finished in 32ms\n   ```\n\n# Usage\n\n## Finding tests\n\n`mt` will recursively look for files in your current directory:\n\n- named `test.{js,mjs}`,\n- or ending in `.test.{js,mjs}`\n- or ending in `_test.{js,mjs}`\n\n## Writing tests\n\nTo write tests you need to import the `test` function from `@sondr3/minitest`. There\nare a couple of different styles that can be used to write tests, but we'll get\ninto these later.\n\n```js\nimport { test } from \"@sondr3/minitest\";\nimport { strict as assert } from \"node:assert\";\n\ntest(\"hello world #1\", () =\u003e {\n  const x = 1 + 2;\n  assert.equal(x, 3);\n});\n\ntest({ name: \"hello world #2\" }, () =\u003e {\n  const x = 1 + 2;\n  assert.equal(x, 3);\n});\n```\n\nYou can use any assertion library you want, like [Chai][chai] for a TDD/BDD\nlike assertions and [Sinon.JS][sinon] to spy and mock functionality. The only\nrequirement is that the assertions throw when they fail.\n\nIf you come from a frameworks like [Jest][jest] you may be surprised to learn\nthat there is no built-in support for nesting tests, or anything like `beforeAll`\nor `beforeEach` in `minitest`. I can highly recommend [this][nesting] article from\nKent C. Dodds about nesting and test hooks. After having used Deno and Rust which do\nnot have such functionality, I don't miss it. I recommend you give it a try!\n\n### Async functions\n\nYou can also test asynchronous code by turning the test function into a function\nthat returns a promise. Simply add `async` in front of the function:\n\n```js\nimport { test } from \"@sondr3/minitest\";\nimport { strict as assert } from \"node:assert\";\n\ntest(\"async hello world\", async () =\u003e {\n  const x = 1 + 2;\n  const wait = async () =\u003e new Promise((res) =\u003e setTimeout(res, 1000));\n  await wait();\n  assert.equal(x, 3);\n});\n```\n\n## Running tests\n\nSimply run `mt` to test all test files matching the pattern in [finding tests](#finding-tests), or\npoint it to the directory or file you want to run:\n\n```shell\n# Run all tests in current directory\nmt\n\n# Run all tests in the fs directory\nmt fs\n\n# Run a single test file\nmt fs.test.js\n```\n\n## Filtering\n\nThere are tree different ways of filtering tests, either by filtering against test\nnames, skipping tests or running a select subset of tests.\n\n### Filtering via the CLI\n\nTests can be filtered out by using the `--filter` option. This option accepts\neither a case insensitive string or a Regex pattern as its value.\n\nIf you have the following tests:\n\n```js\ntest(\"a-test\", () =\u003e {});\ntest(\"test-1\", () =\u003e {});\ntest(\"test-2\", () =\u003e {});\n```\n\nYou can then filter them by filtering all tests that contain the word `test`:\n\n```shell\nmt --filter \"test\"\n```\n\nOr by matching against a Regex pattern:\n\n```shell\nmt --filter \"/test-*\\d/\"\n```\n\n### Ignoring (skipping)\n\nIf you want to ignore/skip tests based on some boolean condition or because they\nare currently incorrect you can use the `ignore()` method or the `ignore` field\nin the options:\n\n```js\ntest(\"ignored\", () =\u003e {}).ignore(); // or .ignore(condition)\ntest({ name: \"other ignored\", ignore: process.arch === \"x64\" }, () =\u003e {});\ntest(\"final ignored\", () =\u003e {}, { ignore: true });\n```\n\n### Running specific tests\n\nSometimes you may want to only run a subset of your tests because you are working\non a problem where you want to ignore tests not relevant to it. To do this you can\nmark tests using the `only()` method or the `only` field in the options, and only\nthese tests are run. While these tests will run normally and report success and\nfailure normally, the whole test suite will still fail as using `only` should only\nbe a temporary measure as it disables nearly the whole test suite.\n\n```js\ntest(\"other ignored\", () =\u003e {}).only();\ntest({ name: \"ignored\", only: true }, () =\u003e {});\ntest(\"final ignored\", () =\u003e {}, { only: true });\n```\n\n## Failing fast\n\nIf you have a test suite that takes a long time to complete or you simply want\nto exit after the first error, one can use the `--fail-fast` option:\n\n```shell\n# fail immediately\nmt --fail-fast\n\n# fail after three failures\nmt --fail-fast 3\n```\n\n## Quiet\n\nThe test output for `mt` can quickly become verbose once the test suite grows, to\nhelp with this one can use the `--quiet` flag to make it far less verbose:\n\n```shell\nmt --quiet\n```\n\n## CLI\n\nFor a complete overview over the available options, use the `--help` flag:\n\n```shell\n$ mt --help\nminitest v0.1.0\nA low-feature and performant test runner inspired by Rust and Deno\n\nUSAGE:\n        mt \u003cdir\u003e [flags]\n\nOPTIONS:\n        -q, --quiet              Quiet output\n        -f, --filter=\u003cfilter\u003e    Filter tests by name, accepts regex\n        -F, --fail-fast=\u003cN\u003e      Fail after N test failures [default: 0]\n        -v, --version            Print version\n        -h, --help               Print help\n```\n\n# Extras\n\n## TypeScript\n\nThere is no built-in support for natively running TypeScript files, they need to\nbe compiled to JavaScript first. In other words, your build step needs to happen\nbefore you run your tests.\n\n## Coverage\n\nTo generate coverate reporting for your tests, I highly recommend using [c8][c8]. It\ngenerates coverage based on the built-in coverage functionality of NodeJS and will\njust magically work with your tests. It is also very fast compared to similar\nfunctionality in other testing libraries. To generate coverage by default, change\nyour `test` script to the following after you've added c8 as a dependency:\n\n```json\n  \"scripts\": {\n    \"test\": \"c8 mt \u003cdir\u003e\",\n  },\n```\n\n## JSX, TSX, browsers\n\nLike with TypeScript, there is no built-in support for usage with JSX and/or TSX,\nand no specific functionality for working against browsers. You may be able to make\nit work, but it is purpose built around testing with Node, so YMMV.\n\n# Rationale\n\nWhy would you use this over the myriad of other test frameworks, runners and libraries\nthat exist? You probably shouldn't, [Jest][jest], [Ava][ava], [tape][tape], [uvu][uvu] and\na whole lot of others are more mature, stable, feature rich and has a wider userbase, but\nif you want a simple Rust/Deno like test framework, this might just scratch your itch.\n\nI also created this as an exercise in learning how testing works under the hood, and had\na lot of fun building it out into a actual useful package. For my needs and packages `minitest`\nis just what I want from a test framework: minimal fuzzing, fast and easy and straight forward.\n\n# License\n\nMIT.\n\n[jest]: https://jestjs.io/\n[ava]: https://github.com/avajs/ava\n[tape]: https://github.com/substack/tape\n[uvu]: https://github.com/lukeed/uvu\n[chai]: https://www.npmjs.com/package/chai\n[sinon]: https://www.npmjs.com/package/sinon\n[c8]: https://github.com/bcoe/c8\n[nesting]: https://kentcdodds.com/blog/avoid-nesting-when-youre-testing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsondr3%2Fminitest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsondr3%2Fminitest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsondr3%2Fminitest/lists"}