Rollup-Plugin-Create-Test-Package-Json

This Rollup plugin supports pack file testing by creating a package.json for a separate project that tests the pack file.

This plugin is used by @toolbuilder/rollup-plugin-test-tools, which tests your pack file in temporary ES, CommonJS, and Electron projects.

This plugin:

• Grabs the external dependencies for the unit tests as Rollup is generating them.
• Uses the package semver ranges in your package.json for the external dependencies.
• Pulls peer dependencies from your package.json.
• Merges the fields you specify in the plugin options into the generated package.json.
• Writes the package.json to Rollup's output.dir or to dirname(output.file) if output.file is specified.

Here's the context in which this plugin is suitable:

• Your tests are ECMAScript modules that Rollup can process.
• You want to reuse your unit tests as package tests, with your package as an external dependency.
• You don't want to manually generate a package.json file for your test project.

Installation

Using npm:

npm install --save-dev rollup-plugin-create-test-package-json

Use

The file rollup.test.config.js in this package provides a complete working example that validates this package before release. You can run it like this:

npm install -g pnpm
pnpm install
pnpm run check:packfile

You can use npm if you change pnpm to npm in rollup.test.config.js.

Options

The plugin works without options. However, you will need the testPackageJson option so you can specify a scripts section and probably some devDependencies for your test runner.

jsonWriter

• Type: AsyncFunction
• Default: a function that pretty prints testPackageJson and writes it to file

Use jsonWriter if you don't like how this plugin writes package.json by default. The parameters are:

• path - the full path name of the package.json file. For example: /tmp/package-test-451/package.json
• json - the package.json Object that the plugin is writing

This is more or less what the default function looks like:

import fs from 'fs-extra'
const defaultJsonWriter = async (path, json) => fs.writeJSON(path, json, { spaces: 2 })

packageJson

• Type: Object|Promise
• Default: the local package.json from disk

This is the package.json of the package you are testing. If your package's package.json isn't suitable, you can use this option. If you set this option, the plugin will not read from the filesystem at all. This option exists primarily to support unit testing.

NOTE: You can pass a Promise that resolves to a package.json Object if you want. That way, you can do some async configuration work in your rollup.config.js. The reject method should be passed an Error object if there is a problem. The error.message will be passed to Rollup, and further processing will stop.

rootDir

• Type: String
• Default: process.cwd()

This option tells the plugin where to look for the project's package.json if the packageJson option is not specified. This plugin will start looking for a package.json at rootDir and walk up the directory structure until it finds one.

outputDir

• Type: String
• Default: output.dir or dirname(output.file) from Rollup configuration

This option tells the plugin where to write the generated package.json file. When using output.dir with rollup-plugin-multi-input, the default outputDir usually works. If you are placing a single file in a subdirectory, then you'll probably want to specify this option.

testPackageJson

• Type: Object|Promise
• Default: boilerplate package.json

This plugin automatically grabs dependencies from the generated unit tests, and picks up the semver ranges from package.json. However, it doesn't know how to run your unit tests. Specify the parts of the package.json required to run the unit tests with this option. Anything you specify will override the values generated by the plugin.

NOTE: You can pass a Promise that resolves to testPackageJson if you want. That way, you can do some async configuration work in your rollup.config.js. The reject method should be passed an Error object if there is a problem. The error.message will be passed to Rollup, and further processing will stop.

Here's a testPackageJson example. If you provide:

  testPackageJson: {
    name: 'awesome-test-package' // copied over directly
    scripts: { test: 'tape -r esm test/**/*.js' }, // copied over directly
    customField: 'whatever', // copied over directly
    dependencies: {
       // lodash will override the value read from packageJson even though it is incompatible,
       // and in a different dependency section. See option.checkSemverConflicts.
      'lodash': '^5.0.0'
    }
    devDependencies: { // devDependencies copied over directly
      "esm": "^3.2.25",
      "tape": "^4.13.2"
    }
  }

But your package's package.json says this:

  "devDepencencies": {
    "lodash": "^4.17.15"
  }

In this example, the plugin will use lodash '^5.0.0' instead of '^4.17.15' in the generated package.json. By default, it would have used '^4.17.15' from the packageJson option. The generated package.json will have lodash': '^5.0.0 in the dependencies section as specified by testPackageJson.

Note that the ranges '^5.0.0' and '^4.17.15' do not intersect. This may be a problem that you want to detect. If so, use options.checkSemverConflicts.

checkSemverConflicts

• Type: boolean
• Default: false

This option only matters if you specify dependencies in the testPackageJson option, and you are copying unit tests from your project to your test project. If the generated package.json specifies a dependency that is incompatible with your unit tests, there will be a problem.

By default, the plugin reads semver ranges from your package.json file or options.packageJson if provided. If your testPackageJson specifies the same dependency, the semver range from testPackageJson will be used instead. If the testPackageJson semver range conflicts with your package.json, there may be a problem. Set this option to true if you want to check if the semver ranges intersect, and generate an error if they do not. The plugin will not generate a package.json file if there is an error.

Contributing

So far, this plugin has only been tested on Linux. Contributions, bug reports, documentation issues, are all very welcome. Please create a pull request or write up an issue.

• 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 test to run unit tests
  • pnpm run check:packfile to show this plugin in action.
  • pnpm run check to validate the package is ready for commit

You can use npm if you change pnpm to npm in rollup.test.config.js.

Issues

This project uses Github issues.

License

MIT