Skip to content

Commit c13a2e0

Browse files
committed
docs(readme): add other examples
1 parent 365b025 commit c13a2e0

File tree

1 file changed

+57
-40
lines changed

1 file changed

+57
-40
lines changed

README.md

Lines changed: 57 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ This package is tested on both Windows and nix (Ubuntu) environments.
5858
- [Examples](#examples)
5959
- [Simple Example](#simple-example)
6060
- [Full Example](#full-example)
61+
- [Fixtures Examples](#fixtures-examples)
6162
- [Appendix](#appendix)
6263
- [Testing Framework Compatibility](#testing-framework-compatibility)
6364
- [Using Babel for Configuration Loading](#using-babel-for-configuration-loading)
@@ -1130,9 +1131,6 @@ Like [`exec`][87], this property cannot appear in the same test object as the
11301131
11311132
## Examples
11321133

1133-
What follows are several babel-plugin-tester [test object][46] examples. See
1134-
[`fixtures`][39] for an example fixtures directory layout.
1135-
11361134
### Simple Example
11371135

11381136
```javascript
@@ -1322,12 +1320,25 @@ pluginTester({
13221320
});
13231321
```
13241322

1323+
### Fixtures Examples
1324+
1325+
See [`fixtures`][39] for an example directory layout or check out some of these
1326+
other projects:
1327+
1328+
<!-- lint disable list-item-style -->
1329+
1330+
- [babel-plugin-transform-rewrite-imports][93]
1331+
- [babel-plugin-explicit-exports-references][94]
1332+
- [babel-plugin-transform-default-named-imports][95]
1333+
1334+
<!-- lint enable list-item-style -->
1335+
13251336
## Appendix
13261337

13271338
### Testing Framework Compatibility
13281339

13291340
This package was originally tested on and built to work with [Jest][7], but it
1330-
is also [tested][93] against [Vitest][11], [Mocha][8], [Jasmine][9], and
1341+
is also [tested][96] against [Vitest][11], [Mocha][8], [Jasmine][9], and
13311342
[`node:test`][10]. See below for details.
13321343

13331344
#### Jest
@@ -1340,7 +1351,7 @@ All babel-plugin-tester features work with Jest. No further action is necessary
13401351
All babel-plugin-tester features work with Vitest, though Vitest don't provide
13411352
global APIs by default. You can either supply some interoperability code (see
13421353
Jasmine or `node:test` below for an example) or run Vitest with the [`--globals`
1343-
CLI option][94].
1354+
CLI option][97].
13441355

13451356
#### Mocha
13461357

@@ -1394,18 +1405,18 @@ examples.
13941405
[`babelOptions.babelrc`][32] and [`babelOptions.configFile`][33] are set to
13951406
`false` by default. This way, you can [manually import (or provide an object
13961407
literal)][68] the exact configuration you want to apply rather than relying on
1397-
babel's [somewhat complex configuration loading rules][95]. However, if your
1408+
babel's [somewhat complex configuration loading rules][98]. However, if your
13981409
plugin, preset, or project relies on a complicated external setup to do its
1399-
work, and you do not mind the [default run order][96], you can leverage [babel's
1400-
automatic configuration loading][97] via the `babelOptions.babelrc` and/or
1410+
work, and you do not mind the [default run order][99], you can leverage [babel's
1411+
automatic configuration loading][100] via the `babelOptions.babelrc` and/or
14011412
`babelOptions.configFile` options.
14021413

14031414
> Fixtures provided via the [`fixtures`][39] option **do not** need to provide a
14041415
> separate `babelOptions.filename` since it will be set automatically. This
14051416
> section only applies to [test objects][46].
14061417
14071418
When relying on `babelOptions.babelrc`, you must also provide a
1408-
[`babelOptions.filename`][98] for each test object that does not include a
1419+
[`babelOptions.filename`][101] for each test object that does not include a
14091420
[`codeFixture`][40] or [`execFixture`][42] property. For example:
14101421

14111422
```javascript
@@ -1443,7 +1454,7 @@ pluginTester({
14431454
```
14441455

14451456
This file does not actually have to exist either, so you can use whatever value
1446-
you want for `filename` as long as the `.babelrc` file is [resolved][99]
1457+
you want for `filename` as long as the `.babelrc` file is [resolved][102]
14471458
properly. Hence, the above example could be simplified further:
14481459

14491460
```javascript
@@ -1480,7 +1491,7 @@ again when run by babel. This is irrelevant to babel-plugin-tester (even if your
14801491
plugin crashes when run outside of babel) and to the overwhelming majority of
14811492
babel plugins in existence. This only becomes a problem if your plugin is
14821493
_aggressively stateful_, which is against the [babel handbook on plugin
1483-
design][100].
1494+
design][103].
14841495

14851496
For example, the following plugin which replaces an import specifier using a
14861497
regular expression will exhibit strange behavior due to being invoked twice:
@@ -1626,12 +1637,12 @@ disables formatting of babel output with prettier):
16261637

16271638
By default, a [formatter][83] is used which formats all babel output with
16281639
[prettier][52]. It will [look for][53] a prettier configuration file relative to
1629-
[the file that's being tested][58] or the [current working directory][101]. If
1640+
[the file that's being tested][58] or the [current working directory][104]. If
16301641
it cannot find one, then it uses the default configuration for prettier.
16311642

16321643
This makes your snapshots easier to read and your expectations easier to write,
16331644
but if you would like to disable this feature, you can either use the [`pure`
1634-
import][102] to disable automatic formatting (along with snapshot serialization)
1645+
import][105] to disable automatic formatting (along with snapshot serialization)
16351646
or you can override the `formatResult` option manually like so:
16361647

16371648
```javascript
@@ -1644,9 +1655,9 @@ pluginTester({
16441655

16451656
### Built-In Debugging Support
16461657

1647-
This package uses [debug][103] under the hood. To view all possible debugging
1658+
This package uses [debug][106] under the hood. To view all possible debugging
16481659
output, including the results of all babel transformations, set the
1649-
`DEBUG='babel-plugin-tester,babel-plugin-tester:*'` [environment variable][104]
1660+
`DEBUG='babel-plugin-tester,babel-plugin-tester:*'` [environment variable][107]
16501661
when running your tests.
16511662

16521663
For example:
@@ -1658,7 +1669,7 @@ NODE_ENV='test' DEBUG='babel-plugin-tester,babel-plugin-tester:*' DEBUG_DEPTH='1
16581669

16591670
#### Available Debug Namespaces
16601671

1661-
The following [debug namespaces][105] are available for activation:
1672+
The following [debug namespaces][108] are available for activation:
16621673

16631674
<!-- lint disable list-item-style -->
16641675

@@ -1681,6 +1692,8 @@ The following [debug namespaces][105] are available for activation:
16811692
- `babel-plugin-tester:tester:eol`
16821693
- `babel-plugin-tester:tester:finalize`
16831694

1695+
<!-- lint enable list-item-style -->
1696+
16841697
The `babel-plugin-tester:tester` namespace and its sub-namespaces each have an
16851698
additional `verbose` sub-namespace that can be activated or deactivated at will,
16861699
e.g. `babel-plugin-tester:tester:verbose` and
@@ -1693,8 +1706,6 @@ For example, to view all debug output except verbose output:
16931706
NODE_ENV='test' DEBUG='babel-plugin-tester,babel-plugin-tester:*,-*:verbose' npx jest
16941707
```
16951708

1696-
<!-- lint enable list-item-style -->
1697-
16981709
### `TEST_ONLY`/`TEST_NUM_ONLY` and `TEST_SKIP`/`TEST_NUM_SKIP` Environment Variables
16991710

17001711
The optional `TEST_ONLY` and `TEST_SKIP` environment variables are recognized by
@@ -1716,7 +1727,7 @@ TEST_SKIP='name of a failing' npx jest
17161727
Given both `TEST_ONLY` and `TEST_SKIP`, tests matched by `TEST_SKIP` will
17171728
_always_ be skipped, even if they are also matched by `TEST_ONLY`. These
17181729
environment variables also override both the fixture-specific
1719-
[`skip`][106]/[`only`][107] and test object [`skip`][108]/[`only`][109]
1730+
[`skip`][109]/[`only`][110] and test object [`skip`][111]/[`only`][112]
17201731
properties _if they conflict_.
17211732

17221733
In addition to `TEST_ONLY` and `TEST_SKIP`, you can also target tests
@@ -1736,7 +1747,7 @@ TEST_NUM_SKIP='5,1, 6-10,, 3,' npx jest
17361747

17371748
`TEST_NUM_ONLY` and `TEST_NUM_SKIP` are meaningless if [`titleNumbering`][57] is
17381749
`false` or your tests are otherwise unnumbered, and may match multiple tests if
1739-
[automatic numbering is restarted][110].
1750+
[automatic numbering is restarted][113].
17401751

17411752
### `setup` and `teardown` Run Order
17421753

@@ -1756,7 +1767,7 @@ the following order:
17561767
The API was inspired by:
17571768

17581769
- ESLint's [RuleTester][ruletester].
1759-
- [@thejameskyle][111]'s [tweet][jamestweet].
1770+
- [@thejameskyle][114]'s [tweet][jamestweet].
17601771
- Babel's own
17611772
[`@babel/helper-plugin-test-runner`][@babel/helper-plugin-test-runner].
17621773

@@ -1963,23 +1974,29 @@ MIT
19631974
[90]: #throws-1
19641975
[91]: https://www.npmjs.com/package/jest-snapshot
19651976
[92]: https://jestjs.io/docs/expect#tomatchsnapshotpropertymatchers-hint
1966-
[93]: ./test/integration/integration-node-smoke.test.ts
1967-
[94]: https://vitest.dev/config#globals
1968-
[95]: https://babeljs.io/docs/en/options#config-loading-options
1969-
[96]: #custom-plugin-and-preset-run-order
1970-
[97]: https://babeljs.io/docs/en/config-files
1971-
[98]: https://babeljs.io/docs/en/options#filename
1972-
[99]: https://babeljs.io/docs/en/config-files#file-relative-configuration
1973-
[100]:
1977+
[93]:
1978+
https://github.com/Xunnamius/babel-plugin-transform-rewrite-imports/blob/main/test/index.test.ts
1979+
[94]:
1980+
https://github.com/Xunnamius/babel-plugin-explicit-exports-references/blob/main/test/index.test.ts
1981+
[95]:
1982+
https://github.com/Xunnamius/babel-plugin-transform-default-named-imports/blob/main/test/index.test.ts
1983+
[96]: ./test/integration/integration-node-smoke.test.ts
1984+
[97]: https://vitest.dev/config#globals
1985+
[98]: https://babeljs.io/docs/en/options#config-loading-options
1986+
[99]: #custom-plugin-and-preset-run-order
1987+
[100]: https://babeljs.io/docs/en/config-files
1988+
[101]: https://babeljs.io/docs/en/options#filename
1989+
[102]: https://babeljs.io/docs/en/config-files#file-relative-configuration
1990+
[103]:
19741991
https://github.com/jamiebuilds/babel-handbook/blob/c6828415127f27fedcc51299e98eaf47b3e26b5f/translations/en/plugin-handbook.md#state
1975-
[101]: https://nodejs.org/api/process.html#processcwd
1976-
[102]: #custom-snapshot-serialization
1977-
[103]: https://npm.im/debug
1978-
[104]: https://www.npmjs.com/package/debug#environment-variables
1979-
[105]: https://www.npmjs.com/package/debug#namespace-colors
1980-
[106]: #skip
1981-
[107]: #only
1982-
[108]: #skip-1
1983-
[109]: #only-1
1984-
[110]: #restarttitlenumbering
1985-
[111]: https://github.com/jamiebuilds
1992+
[104]: https://nodejs.org/api/process.html#processcwd
1993+
[105]: #custom-snapshot-serialization
1994+
[106]: https://npm.im/debug
1995+
[107]: https://www.npmjs.com/package/debug#environment-variables
1996+
[108]: https://www.npmjs.com/package/debug#namespace-colors
1997+
[109]: #skip
1998+
[110]: #only
1999+
[111]: #skip-1
2000+
[112]: #only-1
2001+
[113]: #restarttitlenumbering
2002+
[114]: https://github.com/jamiebuilds

0 commit comments

Comments
 (0)