{"id":15062826,"url":"https://github.com/test-bdd/test-js","last_synced_at":"2026-01-03T00:08:54.679Z","repository":{"id":166808678,"uuid":"635422230","full_name":"test-bdd/test-js","owner":"test-bdd","description":"A testing library for JavaScript that uses behavior-driven development and functional programming.","archived":false,"fork":false,"pushed_at":"2023-09-08T09:10:24.000Z","size":141,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-25T03:46:36.444Z","etag":null,"topics":["behavior-driven-development","behavior-driven-testing","deno","functional-programming","javascript","testing-library","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/test-bdd.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2023-05-02T16:56:09.000Z","updated_at":"2023-05-18T11:41:49.000Z","dependencies_parsed_at":"2025-01-22T04:31:39.478Z","dependency_job_id":null,"html_url":"https://github.com/test-bdd/test-js","commit_stats":null,"previous_names":["test-bdd/test-js"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-bdd%2Ftest-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-bdd%2Ftest-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-bdd%2Ftest-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-bdd%2Ftest-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/test-bdd","download_url":"https://codeload.github.com/test-bdd/test-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243741348,"owners_count":20340455,"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":["behavior-driven-development","behavior-driven-testing","deno","functional-programming","javascript","testing-library","typescript"],"created_at":"2024-09-24T23:47:02.427Z","updated_at":"2026-01-03T00:08:54.643Z","avatar_url":"https://github.com/test-bdd.png","language":"TypeScript","readme":"# testjs\n\nA testing library for JavaScript that uses functional programming. The library works in Deno, Node and the browser.\n\n## Features\n\n- **Functional**: It uses functional programming. So, there are no hidden control flows. The tests run in the order you specify, and nothing apart from what you specify is run. This makes your test easier to reason about.\n- **Behavior-driven Development (BDD)**: It uses behavior-driven development. This means that you test your code according to features or behavior and not implementation. This makes tests easier to write and testing code easier to maintain because even if the implementation changes, your tests don't have to change.\n- **TypeScript**: It supports TypeScript out of the box.\n- **Multiple JavaScript Environment**: It works in Deno, Node and in the browser.\n\n## Comparison with Similar Tools\n\nThis library shares some similarities with [Jest](https://jestjs.io) and [Vitest](https://vitest.dev). Let us take a look at how similar and different this library is from the aforementioned tools.\n\n### Similarities\n\nThis library uses behavior-driven development similar to the one used in Jest and Vitest. It uses the same terminology, such as `expect`, `it`, and `describe`. It also uses patterns and test organization strategies similar to the other tools.\n\n### Differences\n\nThis library uses functional programming while Jest and Vitest use object-oriented programming. This library uses scripts written by the user to run the tests, while the other tools use CLI tools. The other libraries stop at the [suite](#suite) level when it comes to organizing tests. This library on the other hand adds two more levels - [module](#module) and [package](#package).\n\n## Architecture\n\nThe testing library is organized into five levels giving you an easy way to organize your tests.\n\n```\n|-- Package\n|   |-- Module\n|   |   |-- Suite\n|   |   |   |-- Step\n|   |   |   |   |-- Expectation\n```\n\n### Expectation\n\nThis the building block of all tests. It tests if a test meets a particular expectation. For example, if you are testing a function, you can test if the function returns a correct value for a specific input. This level is handled by [`expect`](./docs/api.md#expect).\n\n### Step\n\nA group of related `Expectation`s. It tests if the test subject meets the requirements for a group of expectations. For example, if you are testing a function, you can test if the function returns the correct value for a group of inputs that are related. This level is handled by [`it`](./docs/api.md#it).\n\n### Suite\n\nA group of related `Step`s. It tests if a particular feature is provided correctly by the test subject. For example, it can be used to test whether or not a function works correctly for its use case. This level is handled by [`describe`](./docs/api.md#describe).\n\n### Module\n\nA group of related `Suite`s. It tests if a group of related features are provided correctly by the test subject. For example, you can use it to test if a group of related functions provide the expected features. This level is handled by [`mod`](./docs/api.md#mod).\n\n### Package\n\nThis is the top-most test. It is a group of `Module`s. This level is handled by [`pack`](./docs/api.md#pack).\n\n## Usage\n\n### Synchronous\n\n```ts\n// Deno\nimport { describe, toEqual } from 'https://deno.land/x/testjs/mod.ts';\n\n// Node ESM\n// import { describe, toEqual } from '@test-bdd/testjs';\n\n// Node CommonJS\n// const { describe, toEqual } = require('@test-bdd/testjs');\n\n// Test subject\nconst isEven = (num: number) =\u003e num % 2 === 0;\n\ndescribe('isEven', (it) =\u003e {\n  it('should return true for multiples of 2', (expect) =\u003e {\n    expect(isEven(2), toEqual(true)); // PASSED\n    expect(isEven(100), toEqual(true)); // PASSED\n  });\n\n  it('should return true for 0', (expect) =\u003e {\n    expect(isEven(0), toEqual(true)); // PASSED\n  });\n});\n```\n\n### Asynchronous\n\n```ts\n// Deno\nimport {\n  describe,\n  toBeGreaterThanOrEqual,\n  toBeLessThan\n} from 'https://deno.land/x/testjs/mod.ts';\n\n// Node ESM\n// import {\n//   describe,\n//   toBeGreaterThanOrEqual,\n//   toBeLessThan\n// } from '@test-bdd/testjs';\n\n// Node CommonJS\n// const {\n//   describe,\n//   toBeGreaterThanOrEqual,\n//   toBeLessThan\n// } = require('@test-bdd/testjs');\n\n// Test subject\nconst delay = (timeMilliseconds: number) =\u003e {\n  return new Promise((resolve) =\u003e {\n    setTimeout(() =\u003e {\n      resolve();\n    }, timeMilliseconds);\n  });\n};\n\ndescribe('delay', async (it) =\u003e {\n  await it('should delay by 1s', async (expect) =\u003e {\n    const timeMilliseconds = 1000;\n    const time = performance.now();\n    await delay(timeMilliseconds);\n    const finalTime = performance.now() - time;\n    expect(finalTime, toBeGreaterThanOrEqual(timeMilliseconds));\n    expect(finalTime, toBeLessThan(timeMilliseconds * 2));\n  });\n});\n```\n\n## Running Tests\n\nYou can run tests by simply running the scripts containing the tests. However, the library comes with a test runner that provides a flexible way of running tests.\n\n### Running Scripts\n\n#### Deno\n\nIn deno, you can run a script using `deno run main.test.ts` where `main.test.ts` is the name of the test script. You can also create a task in `deno.jsonc` file to avoid repeated typing of long text. A task for running tests may look like the following:\n\n```json\n{\n  \"tasks\": {\n    \"test\": \"deno run main.test.ts\"\n  }\n}\n```\n\nTo run the script, use `deno task test`.\n\nDo not forget to include necessary flags. For example, if the tests need file read and write permissions, you can modify the above task as follows:\n\n```json\n{\n  \"tasks\": {\n    \"test\": \"deno run --allow-read --allow-write main.test.ts\"\n  }\n}\n```\n\n#### Node\n\nIn Node.js, you can run scripts by using `node main.test.js` assuming `main.test.js` is the test file. You can create a script in `package.json` to avoid repetition. The script would look like the following:\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"node main.test.ts\"\n  }\n}\n```\n\nTo run the script, use `node run test`.\n\n### Using the Test Runner\n\nRefer to the documentation for the [test runner](./docs/test-runner.md).\n\n## Output\n\n### Syntax\n\nThe following is the syntax for the output of a test at any level:\n\n```sh\nOUTCOME (TESTS_PASSED/TOTAL) TIMEms [: DESCRIPTION]\n```\n\nwhere\n\n- `OUTCOME` indicates whether the test passed or failed. It can either be `PASSED` or `FAILED`.\n- `TESTS_PASSED` is the number of tests that have passed.\n- `TOTAL` is the total number of tests.\n- `TIME` is the time (in milliseconds) taken to run all tests at that level.\n- `DESCRIPTION` is the description you provide for the test. It is optional.\n\n### Examples\n\nThe following examples provide possible outputs for the test given in [Usage](#synchronous);\n\n#### All Passed\n\n```sh\nPASSED (2/2) 5ms: isEven\n  PASSED (2/2) 3ms: it returns true for multiples of 2\n    PASSED (1/1) 1ms\n    PASSED (1/1) 2ms\n  PASSED (1/1) 2ms: it returns true for 0\n    PASSED (1/1) 2ms\n```\n\n#### Some Passed\n\nIf a test fails, all tests at higher levels of that test are also considered to have failed.\n\n```sh\nFAILED (1/2) 5ms: isEven\n  PASSED (2/2) 3ms: it returns true for multiples of 2\n    PASSED (1/1) 1ms\n    PASSED (1/1) 2ms\n  FAILED (0/1) 2ms: it returns true for 0\n    FAILED (0/1) 2ms: false is not equal to true\n```\n\n#### All Failed\n\n```sh\nFAILED (0/2) 5ms: isEven\n  FAILED (0/2) 3ms: it returns true for multiples of 2\n    FAILED (0/1) 1ms: false is not equal to true\n    FAILED (0/1) 2ms: false is not equal to true\n  FAILED (0/1) 2ms: it returns true for 0\n    FAILED (0/1) 2ms: false is not equal to true\n```\n\n## API\n\nCheck out the [API documentation](./docs/api.md) for more.\n\n## License\n\nApache 2.0.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftest-bdd%2Ftest-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftest-bdd%2Ftest-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftest-bdd%2Ftest-js/lists"}