Rollup Plugin Test Tools

Rollup.js configurations to test your pack file before publishing. It runs your unit tests against your packfile in an ES project, a CommonJS project, and in Electron. This is primarily for dual module packages.

Here are the basic steps and the plugins used:

• converts your units tests so that they use package instead of relative imports (e.g. "../src/index.js" to "your-package-name")
  • rollup-plugin-multi-input
  • rollup-plugin-relative-to-package
• builds ES, CommonJS, and browser (runs in Electron) test projects around those tests
  • rollup-plugin-create-test-package-json
  • rollup-plugin-create-pack-file
• and run the unit tests in the temporary test project
  • @toolbuilder/rollup-plugin-commands

The configurations have these requirements:

• Unit tests are written as ES modules
• Since the pack file is being tested, the unit tests must use only package imports that are accessible when using the package.
• Unit tests produce TAP output and are standalone - I use zora because it also runs in the browser.
• Unit tests match this glob test/**/*test.js
• Source code matches this glob src/**/*.js
• The pnpm package manager is installed globally on your system for the temporary projects to use.

If your package needs something else, this package exports the plugins above, and some other functionality, to make creating your configurations easier.

Install

npm install --save-dev @toolbuilder/rollup-plugin-test-tools

Use

For the ES and CommonJS tests, Rollup bundles your unit tests as ES or CommonJS modules depending on the test. The dependencies are installed in the temporary test package by pnpm. The browser test builds a UMD file from your package source, unit tests, and your dependencies. It will try to bundle your dependencies with a default Rollup configuration. This may or may not work depending on your package dependencies. If it doesn't work, you'll need to create a custom configuration. The package @toolbuilder/pouchdb-paginated-query provides an example.

ES Module Test Configuration

To run the ES test on your packfile create a rollup.config.js configuration file like this:

export { nodeEsTestConfig as default } from '@toolbuilder/rollup-plugin-test-tools'

Then call rollup either via the CLI or the API. The name and purpose of nodeEsTestConfig will be stable, but the configuration object may change.

CommonJS Module Test Configuration

To run the CommonJS test on your packfile create a rollup.config.js configuration file like this:

export { nodeCommonJsTestConfig as default } from '@toolbuilder/rollup-plugin-test-tools'

Then call rollup either via the CLI or the API. The name and purpose of nodeCommonJsTestConfig will be stable, but the configuration object may change.

Browser Module Test Configuration

To run the Electron (browser) test on your packfile create a rollup.config.js configuration file like this:

export { browserTestConfig as default } from '@toolbuilder/rollup-plugin-test-tools'

Then call rollup either via the CLI or the API. The name and purpose of browserTestConfig will be stable, but the configuration objects may change.

As noted above, the browser test builds a UMD file from your package source, unit tests, and your unit tests. You may need a custom configuration.

All-in-one configuration

As a convenience, all Rollup configurations exported by this package can be imported together. Rollup will run them one by one. Just create a a rollup.config.js configuration file like this:

// Runs ES module test, CommonJS module test, then browser test in Electron
export { testConfigs as default } from '@toolbuilder/rollup-plugin-test-tools'

Then call rollup either via the CLI or the API.

Exported Helpers

import { tempPath, basePackfileTestConfig } from '@toolbuilder/rollup-plugin-test-tools'

The function tempPath creates a unique temporary path. See src/temp-path.js for the JSDoc. This function should be stable.

The function basePackfileTestConfig creates a Rollup configuration for either a ES or CommonJS module. See src/node-configs.js for the JSDoc and examples. The name and purpose of basePackfileTestConfig will be stable, but userOptions parameter may change, and the returned configuration object may change.

Exported Dependencies

Some of this package's dependencies are exported for convenience. Links to documentation for these packages are provided above.

// These are the export statements
export { default as createTestPackageJson } from 'rollup-plugin-create-test-package-json'
export { default as multiEntry } from '@rollup/plugin-multi-entry'
export { default as multiInput } from 'rollup-plugin-multi-input'
export { default as relativeToPackage } from 'rollup-plugin-relative-to-package'
export { default as createPackFile } from '@toolbuilder/rollup-plugin-create-pack-file'
export { default as runCommands, shellCommand } from '@toolbuilder/rollup-plugin-commands'

Stability

This package will have a looser interpretation of semver numbering. For example adding @rollup/plugin-commonjs to the browser configuration does not affect my projects, but it might affect yours. So what I might think it is a small point change, might be a breaking change for you.

Contributing

Contributions are encouraged. Please create an issue or a pull request.

• I use pnpm instead of npm.
• Run the unit tests with pnpm test
• Package verification requires pnpm to be installed globally.
  • npm install -g pnpm
  • pnpm install
  • pnpm run check:packfile to test against Node ES and CommonJS projects, as well as Electron.
  • pnpm run check to validate the package is ready for commit

Ironically, this project has no tests for itself. I use the packfile against some of my other projects. If you have a nice way to fix this, let me know!

Issues

This project uses Github issues.

License

MIT