{"id":15021397,"url":"https://github.com/spockjs/spockjs","last_synced_at":"2025-10-28T16:31:28.137Z","repository":{"id":57162036,"uuid":"112468300","full_name":"spockjs/spockjs","owner":"spockjs","description":"Structured JavaScript test cases, inspired by Spock Framework","archived":false,"fork":false,"pushed_at":"2018-08-13T13:01:09.000Z","size":613,"stargazers_count":13,"open_issues_count":9,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-28T02:41:02.402Z","etag":null,"topics":["babel","javascript","plugin","spock","spock-framework","structure","test","testing"],"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/spockjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-29T11:40:47.000Z","updated_at":"2024-05-02T12:22:46.000Z","dependencies_parsed_at":"2022-09-10T07:01:51.741Z","dependency_job_id":null,"html_url":"https://github.com/spockjs/spockjs","commit_stats":null,"previous_names":["jeysal/babel-plugin-spock"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spockjs%2Fspockjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spockjs%2Fspockjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spockjs%2Fspockjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spockjs%2Fspockjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spockjs","download_url":"https://codeload.github.com/spockjs/spockjs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219859166,"owners_count":16556037,"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":["babel","javascript","plugin","spock","spock-framework","structure","test","testing"],"created_at":"2024-09-24T19:56:31.979Z","updated_at":"2025-10-28T16:31:22.767Z","avatar_url":"https://github.com/spockjs.png","language":"TypeScript","readme":"# spockjs\n\n\u003e Structured JS test cases, inspired by\n\u003e [Spock Framework](http://spockframework.org)\n\n[![build status](https://img.shields.io/travis/spockjs/spockjs/master.svg?style=flat-square)](https://travis-ci.org/spockjs/spockjs)\n[![AppVeyor build status](https://img.shields.io/appveyor/ci/jeysal/spockjs/master.svg?style=flat-square\u0026label=windows+build)](https://ci.appveyor.com/project/jeysal/spockjs)\n[![code coverage](https://img.shields.io/codecov/c/github/spockjs/spockjs/master.svg?style=flat-square)](https://codecov.io/gh/spockjs/spockjs)\n\n[![npm package](https://img.shields.io/npm/v/@spockjs/babel-plugin-spock.svg?style=flat-square)](https://www.npmjs.com/package/@spockjs/babel-plugin-spock)\n[![license](https://img.shields.io/github/license/spockjs/spockjs.svg?style=flat-square)](https://github.com/spockjs/spockjs/blob/master/LICENSE)\n\n**Note:** This project is in an early stage of development and currently provides\nonly a small set of features.\n\n## Example test case\n\n```javascript\ntest('basic arithmetic', () =\u003e {\n  expect: {\n    1 + 2 === 3;\n    3 * 3 \u003e= 4 * 4; // falsy\n  }\n});\n```\n\n```\n(3 * 3 \u003e= 4 * 4) is not truthy   # test.js:4\n\n  _assert(3 * 3 \u003e= 4 * 4, \"(3 * 3 \u003e= 4 * 4) is not truthy\")\n            |   |    |\n            |   |    16\n            9   false\n```\n\n## Installation\n\n    npm install --save-dev @spockjs/babel-plugin-spock power-assert\n\nThis project is a [Babel](https://babeljs.io/) plugin that needs to transform\nyour test sources in order to generate assertions, so your test runner will need\nsupport for Babel. Babel integrates quite nicely into most modern test runners.\nCheck the documentation of your test runner for instructions on how to configure\nBabel (e.g. for\n[Jest](https://facebook.github.io/jest/docs/en/getting-started.html#using-babel),\n[AVA](https://github.com/avajs/ava/blob/master/docs/recipes/babel.md) etc.)\nor consult Babel's own [documentation](http://babeljs.io/docs/setup/).\n\nOnce Babel is set up for your test files, simply add `\"@spockjs/babel-plugin-spock\"`\nto the `plugins` array in your babel configuration and you're good to go.\nIf you do not already use ES modules via Babel,\nyou will also need to set up Babel for transforming ES2015 imports (usually via\n[@babel/preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env)\n) so the assert helpers can be imported automatically.\n\n**Note:** This plugin requires Babel 7. Babel 6 is no longer supported.\n\n### TypeScript\n\nIt is possible to use this plugin with TypeScript,\nbut only if you compile the TypeScript code with Babel (`@babel/preset-typescript`).\nThe official TypeScript compiler (`tsc`) is not supported.\n\n### Test runners\n\nThe plugin should work with all test runners by default\n(perhaps with occasional config tweaks to the runners).\nYou can take a look at [our integration tests](integration-tests)\nto see how we configured each runner that is tested.\n\nNevertheless, we provide additional tweaks and features\nto improve the experience with some popular test runners.\nIf your runner appears in the list below, it is recommended\nyou `npm install --save-dev` the corresponding package and\nadd it to the `presets` in the plugin's [config file](#configuration)\nfor a flawless experience.\n\n#### Jest\n\n**Package**: `@spockjs/preset-runner-jest`\n\n**Currently provides**\n\n- assertion messages that show what went wrong\n\n#### AVA\n\n**Package**: `@spockjs/preset-runner-ava`\n\n**Currently provides**\n\n- internal use of native AVA assertions\n  - no need to configure `\"failWithoutAssertions\": false`\n  - assertion errors look just like in regular AVA\n\n**Peculiarities**:\n\n- AVA's `t` must be available in the test cases;\n  using a different name for the test case parameter is not currently supported.\n  If you do not follow this convention in all your test cases,\n  you will have to disable `@spockjs/preset-runner-ava` and\n  use the \"vanilla\" spockjs with its disadvantages.\n\n## Usage\n\n### Assertion blocks\n\nInside of a block labeled with `expect:` or `then:`, all statements will be\nconsidered assertions and evaluated to check for truth:\n\n```javascript\nexpect: {\n  1 \u003c 2;\n}\n```\n\n`when`-`then` blocks can be particularly useful and expressive for code with\nside effects:\n\n```javascript\n// The 'when' label here does not have a special meaning\n// It is used simply to make the test more structured\nwhen: {\n  abc.setXyz(1);\n}\n\nthen: {\n  abc.getXyz() === 1;\n}\n```\n\nSingle labeled statements are also possible:\n\n```javascript\nexpect: 'a' + 'b' === 'ab';\n```\n\nNote that these blocks can only contain statements that can be evaluated as\nexpressions. For example, an if statement would not be valid:\n\n```javascript\n// BAD\nexpect: {\n  if (x \u003c 1) x === 0.5;\n  else x === 2;\n}\n```\n\nHowever, you can nest an assertion block into other structures:\n\n```javascript\n// GOOD\nif (x \u003c 1) expect: x === 0.5;\nelse expect: x === 2;\n```\n\nIf you want to perform more complicated checks, it might be helpful to look for\nsmall helper libraries on npm. For example,\n[deep-strict-equal](https://github.com/sindresorhus/deep-strict-equal) can help\nperform deep equality checks on object structures. In the future, this plugin\nmight provide special syntax for such use cases.\n\nOf course, you still have the option to use your native assertion library\nalongside assertion blocks wherever you consider it appropriate.\nSome assertion libraries may provide features on top of what this plugin supports.\n\n### Linters\n\nThe test you will write using this plugin often employ syntax that is otherwise\nuncommon in JavaScript code. For this reason, if you use a linter such as\n[ESLint](https://eslint.org/), you will likely see annoying warnings all over\nyour tests. To work around this, most linters will give you multiple options:\n\n- Disable the problematic rules with special annotations in your test files.\n  This can be a hassle because it needs to be done for every file.\n- Completely disable the rules in the configuration. This means that they will\n  no longer apply to production code either.\n- Create a separate config for tests that extends the base config, but disables\n  the rules.\n\nIf you're using TypeScript, tsc might also complain about unused labels.\n`allowUnusedLabels` can turn those warnings off.\n\n## Configuration\n\nYou can configure this plugin using Babel's regular\n[plugin configuration mechanism](https://babeljs.io/docs/plugins/#pluginpreset-options).\nThe following options are available:\n\n**`powerAssert`**\n\nThe plugin can seamlessly generate assertions that produce detailed mismatch\nmessages to help you figure out what exactly about the assertion went wrong.\nTurning this feature off could be useful if you're tests appear to run slowly or\nyou are experiencing other issues with your assertions.\n\nThis feature is powered by the awesome project\n[power-assert](https://github.com/power-assert-js/power-assert).\n\ntype: `boolean`  \ndefault: `true`\n\n**`autoImport`**\n\nThe plugin transforms your assertion blocks to calls to an assert function.\nBy default (`true`), this function is automatically imported from `power-assert`.\nYou can set this option to a string containing the name of a module\nthat exports an assert function as its default export\nto use that module for assertions instead.\n\nYou can also set this option to `false` to disable automatic imports.\nYou will then have to provide a function named `assert` yourself\nin your test files wherever you use assertion blocks.\n\ntype: `boolean | string`  \ndefault: `true` (`'power-assert'`)\n\n**`staticTruthCheck`**\n\nThe plugin can try to statically evaluate your assertion expressions at compile-time\nand throw an error if they can be inferred to always be truthy or to always be falsy.\nSuch expressions sometimes indicate a test that does not provide any value.\n\nHere's an example of an assertion expression that can be inferred to always be truthy:\n\n```javascript\nconst x = 1;\nexpect: x === 1;\n```\n\ntype: `boolean`  \ndefault: `false`\n\n**`assertFunctionName`**\n\nThe plugin will automatically define an assert import or use an existing one.\nYou can set this option to enforce a specific name for the generated assert calls.\n\ntype: `string`  \ndefault: empty string (generated identifier)\n\n**`presets`**\n\nPresets are collections of additional features or behavior tweaks for the plugin.\nThe plugin will import modules with the exact names specified in this array and use them as presets.\nSee [Test runners](#test-runners) for some presets provided by spockjs itself.\n\nTo implement your own preset, take a look at one of the `@spockjs/preset-*` packages.\nThe exports of a preset module must match the `Hooks` type defined by `@spockjs/config`.\n\ntype: `string[]`  \ndefault: `[]`\n\n## Escape route\n\nIn case you wish to stop using this plugin at some point,\nbut of course don't want to rewrite all of your tests manually,\nthere is always an escape hatch available.\nWe also have an [integration test](test/integration/codemod.test.ts)\nto safeguard this possibility.\n\n### Codemod configuration\n\nCreate a `config.json`:\n\n```json\n{\n  \"plugins\": [\n    [\n      \"@spockjs/babel-plugin-spock\",\n      {\n        \"powerAssert\": false,\n        \"autoImport\": \"assert\",\n        \"assertFunctionName\": \"assert\"\n      }\n    ]\n  ]\n}\n```\n\n#### Explanation\n\nWe turn off `powerAssert` because it generates a lot of unreadable code.  \nWe set `autoImport` to `assert` instead of the default `powerAssert`\nto also switch back to the native node `assert` module\nas we move away from the plugin.  \nWe set the `assertFunctionName` to `assert`\nto avoid auto-generated identifiers in our tests.\nNote that you must ensure your tests\ndo not declare an `assert` identifier themselves\nto avoid a potential collision.\n\n### Running the codemod\n\nTo transform a test file with Babel and **overwrite it immediately**, execute\n\n```sh\nnpx --no-install babel --no-babelrc --config-file ./config.json \\\nyour-test-file.js --out-file your-test-file.js\n```\n\n`npx --no-install babel` executes your local (package-wide) Babel installation.\nIf you do not have `@babel/cli` installed locally,\nyou can also `npm install -g @babel/core @babel/cli` it globally.\nThe `--no-babelrc` and `--config-file` Babel options ensure that\nwe only apply exactly the changes from the plugin.\n\nYou can also use Babel to apply the changes to an entire folder of tests:\n`npx [...] tests --out-dir tests`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspockjs%2Fspockjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspockjs%2Fspockjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspockjs%2Fspockjs/lists"}