{"id":16528961,"url":"https://github.com/satya164/babel-test","last_synced_at":"2025-05-07T04:44:23.374Z","repository":{"id":56589117,"uuid":"150899511","full_name":"satya164/babel-test","owner":"satya164","description":"An opinionated library to make testing babel plugins easier.","archived":false,"fork":false,"pushed_at":"2022-12-13T13:08:38.000Z","size":6256,"stargazers_count":80,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-18T08:39:14.272Z","etag":null,"topics":["babel","fixtures","hacktoberfest","jest","jest-snapshots","snapshot"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/satya164.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-29T20:13:39.000Z","updated_at":"2023-09-08T17:45:35.000Z","dependencies_parsed_at":"2023-01-28T12:31:15.577Z","dependency_job_id":null,"html_url":"https://github.com/satya164/babel-test","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satya164%2Fbabel-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satya164%2Fbabel-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satya164%2Fbabel-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satya164%2Fbabel-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/satya164","download_url":"https://codeload.github.com/satya164/babel-test/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251352525,"owners_count":21575859,"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","fixtures","hacktoberfest","jest","jest-snapshots","snapshot"],"created_at":"2024-10-11T17:42:32.672Z","updated_at":"2025-05-07T04:44:23.352Z","avatar_url":"https://github.com/satya164.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# babel-test\n\n[![Build Status][build-badge]][build]\n[![Code Coverage][coverage-badge]][coverage]\n[![MIT License][license-badge]][license]\n[![Version][version-badge]][package]\n\nAn opinionated library to make testing babel plugins easier.\n\n\u003cimg alt=\"Demo\" src=\"demo/demo.gif\" width=\"626\"\u003e\n\n## Why\n\nI like to use fixture files instead of snapshots for testing my babel plugins because it's easier to read with proper syntax highlighting. But I missed the features of snapshots, i.e. creating and updating snapshots with press of a key. It was too annoying to copy paste transformed code from the terminal every time. So I wanted to make something which integrates with Jest's snapshot feature.\n\nI also felt that the current solutions add too much abstraction and I wanted to make something simpler. I built this instead of contributing to existing tools because it's not addressing lack of features in existing tools, but exploring a different API.\n\nThe tool works with [Jest](https://jestjs.io/) (recommended) or any testing framework which provides the `describe` and `it` global functions, such as [Mocha](https://mochajs.org/).\n\n## Installation\n\n```sh\nnpm install --save-dev babel-test\n```\n\nor\n\n```sh\nyarn add --dev babel-test\n```\n\n## Usage\n\nThe library exports a `create` function, which you can use to create helpers for your test using a babel config. The `fixtures` function from the returned object can be used to run tests against a directory containing fixtures:\n\n```js\nimport path from 'path';\nimport { create } from 'babel-test';\n\nconst { fixtures } = create({\n  plugins: [require.resolve('./my-plugin')],\n});\n\nfixtures('my plugin', path.join(__dirname, '__fixtures__'));\n```\n\n## API\n\nCalling the `create` function with a babel config returns an object with `test` and `fixtures` functions:\n\n```js\nimport { create } from 'babel-test';\n\nconst { test, fixtures } = create({\n  plugins: [require.resolve('./my-plugin')],\n});\n```\n\nThe `create` function accepts the same [`options` object as Babel](https://babeljs.io/docs/en/options). It'll additionally set `babelrc` and `configFile` options to `false` by default if you haven't explicitly passed them. This avoids your tests being affected by external babel configuration.\n\n### Testing fixtures\n\nTo run the tests against a directory with fixtures, you can use the `fixtures` function returned from `create`:\n\n```js\nfixtures('my plugin', path.join(__dirname, '__fixtures__'));\n```\n\nIt accepts a title for the `describe` block and the absolute path to the directory containing the fixtures.\n\nThe fixtures directory should contain subdirectories with test files. Every test should contain a `code.js` file, which will be used as the input. If the transform should throw, it should have an `error.js` file. If the transform should pass, it should have an `output.js` file with the transformed code. The title for each test will be based the name of the directory. The first argument is used as the title for the describe block.\n\n```sh\n.\n├── function-expression\n│   ├── code.js\n│   └── output.js\n├── invalid-syntax\n│   ├── code.js\n│   └── error.js\n└── simple-variable\n    ├── code.js\n    └── output.js\n```\n\nYou can use `fixtures.skip` and `fixtures.only`, similar to Jest's `describe.skip` and `describe.only`. To skip an individual fixture, you can rename the fixture's directory to `skip.name-of-the-fixture`, and to run a specific fixture only, you can rename the fixture's directory to `only.name-of-the-fixture`.\n\nTo use hooks such as `beforeEach`, `afterEach`, `beforeAll` and `afterAll`, you can pass an object with these properties as the third argument:\n\n```js\nfixtures('my plugin', path.join(__dirname, '__fixtures__'), {\n  beforeEach() {\n    // Do some setup here\n  },\n});\n```\n\nBy default, it will compare the outputs with the files on the filesystem and you have to manually update the files in case of a mismatch. If you're using Jest, you can use the snapshot feature to automatically update the files with a keypress. ([See below](#integration-with-jest-snapshot)) on how to set it up.\n\n### Standalone test\n\nTo run a standalone test with some custom logic, you can use the `test` function returned from `create`:\n\n```js\ntest('transpiles const to var', ({ transform }) =\u003e {\n  const { code } = await transform('const foo = 42', { filename: 'foo.js' });\n\n  expect(code).toBe('var foo = 42');\n});\n```\n\nIt accepts a title for the test and a callback containing the test. The callback will receive a `transform` function, and should return a promise if it's asynchronous. The `transform` function takes an optional second parameter containing additional options for Babel, useful for passing additional information such as `filename` required by some plugins.\n\nYou can use `test.skip` and `test.only`, similar to Jest's `it.skip` and `it.only`.\n\n### Custom transform\n\nSometimes it's useful to test a plugin against a different babel instance. You can pass a `transform` function to `create` instead of a `config` object to test against a custom babel instance:\n\n```js\nconst { test, fixtures } = create((code, options) =\u003e\n  // transform function for babel 6\n  require('babel-core').transform(\n    code,\n    Object.assign(\n      {\n        babelrc: false,\n        plugins: [require.resolve('./my-plugin')],\n      },\n      options\n    )\n  )\n);\n```\n\nThe custom `transform` function will receive the `code` and additional `options` for babel (such as `filename`) and should return an object with `code` property containing the transformed code.\n\nIf you're using the same fixtures directory with a different transform function, keep in mind that the same plugins can produce slightly different code in a different Babel version, and it's likely that error stack traces will be different. In these cases, there will be conflicts when updating the snapshots. It'll be better to separately test those fixtures for the different transforms to avoid conflicts.\n\n## Integration with Jest snapshot\n\nIntegrating with Jest snapshots allows you to automatically create and update output files. To integrate with Jest snapshots, you need to:\n\nInstall and add the [jest-file-snapshot](https://github.com/satya164/jest-file-snapshot) matcher:\n\n```js\nimport { toMatchFile } from 'jest-file-snapshot';\n\nexpect.extend({ toMatchFile });\n```\n\nThen configure the Jest watcher to ignore output files by adding the following under the `jest` key in `package.json`:\n\n```json\n\"watchPathIgnorePatterns\": [\n  \"__fixtures__\\\\/[^/]+\\\\/(output|error)\\\\.js\"\n]\n```\n\nNow you can create and update the output files like you would do with snapshots.\n\n## Alternatives\n\n- [`babel-plugin-tester`](https://github.com/babel-utils/babel-plugin-tester)\n- [`@babel/helper-plugin-test-runner`](https://github.com/babel/babel/tree/master/packages/babel-helper-plugin-test-runner)\n\n## Contributing\n\nMake sure your code passes the unit tests, ESLint and TypeScript. Run the following to verify:\n\n```sh\nyarn test\nyarn lint\nyarn typescript\n```\n\nTo fix formatting errors, run the following:\n\n```sh\nyarn lint -- --fix\n```\n\n\u003c!-- badges --\u003e\n\n[build-badge]: https://img.shields.io/circleci/project/github/satya164/babel-test/main.svg?style=flat-square\n[build]: https://circleci.com/gh/satya164/babel-test\n[coverage-badge]: https://img.shields.io/codecov/c/github/satya164/babel-test.svg?style=flat-square\n[coverage]: https://codecov.io/github/satya164/babel-test\n[license-badge]: https://img.shields.io/npm/l/babel-test.svg?style=flat-square\n[license]: https://opensource.org/licenses/MIT\n[version-badge]: https://img.shields.io/npm/v/babel-test.svg?style=flat-square\n[package]: https://www.npmjs.com/package/babel-test\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatya164%2Fbabel-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsatya164%2Fbabel-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatya164%2Fbabel-test/lists"}