setup-env

We've reached peak programming. Complex toolchains making our development lives easier. So why not apply this to testing. But instead of complex, we just run a couple of scripts, instead of massive configuration files, just nothing and instead of you writing code, a module that does it for you. Sounds to good to be true? It probably is, sorry.

You might wonder how this project will actually help you out, it automates the following setup process's for your tests:

Babel integration, ensures your tests are compiled with the same babel presets as the rest of your code.
Set the correct env, something that is easily forgotten, NODE_ENV=test, but we gotchu fam.
Support for loading static files using require. Not as fancy as WebPack, at least it will make your code run instead of throw.
Shallow rendering, correctly setup and pre-configured with JSDOM, as it should.

Still not convinced? Here's some expert reviews:

This shizz is lit fam       require, done, izipizi    Best module ever installed
          - Ya homies            - Your co-workers              - Everybody else

Installation

The package is released in the public npm registry under the setup-env name and should be installed as devDependency in your project:

npm install --save-dev setup-env

Then require the file before your tests are imported, for example with mocha you can use the --require file to achieve this:

mocha --require setup-env ./test/*.test.js

And for jest you can leverage the setupFiles array in your jest.config.js:

{
  setupFiles: ['setup-env']
}

And that's it, your project is configured.

Configuration

First of all, configuration is optional, this library works out of the box for the dependencies you have installed in your project. Customizing how we setup the environment is done using a special setup key in your package.json:

{
  "name": "example-package",
  "description": "ignore this, this is content filler",
  ...

  "setup": {
    "userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.9)"
  },

  ...
  "devDependencies": {
    "@babel/register": "latest",
    "enzyme-adapter-react-17": "latest",
    ...
  }
}

The following keys inside the setup object can be configured:

steps
babel
jsdom
loaders
extensions

steps

These are the steps that we execute (in order) to prepare the environment for testing. The following steps are executed:

env Ensure that a proper NODE_ENV is set before testing.
register Enable @babel/register or the ancient babel-register.
enzyme Automatically configure the Enzyme adapter.
jsdom Prepare the environment with JSDOM.
static Allows requiring of static files such as .css and .jpg files.

{
  "setup": {
    "steps": ['static']
  }
}

The code above will prevent every step to run, except our static integration. Please note, that you don't need to explicitly turn off the enzyme or register steps if you don't use @babel/register or enzyme in your project. This project is smart enough to ignore them if they are not installed.

babel

Provide custom options to the @babel/register loader. This gives you full control on how babel processes the files that you require in your test suite.

{
  "setup": {
    "babel": {
      "cache": false
    }
  }
}

It also support the ancient babel-register package, if you are building a new project we encourage you to use the latest and greatest.

jsdom

Introduces JSDOM based globals in the environment so you can use window, document and other DOM based globals in your test suite without issues. Additionally this will ensure that the { mount } functionality of enzyme works.

{
  "setup": {
    "jsdom": {
      "storageQuota": 10000000,
      "referrer": "https://example.com/"
    }
  }
}

Additional, the userAgent can be configured using the userAgent key in setup.

extensions

It's not uncommon that you compile your code with WebPack and that you import asserts inside your code such as css files or static images. These are not supported by Node as it only understands JavaScript. We will automatically patch the environment to ensure that these dependencies can be loaded inside Node.js. The extensions option allows you to configure which extensions need to be patched. We have a list with common media types for css, fonts, images and video/audio files. But you can create your own list using this option.

{
  "setup": {
    "extensions": [
      ".css",
      ".sass",
      ".example"
    ]
  }
}

loaders

This option is used in pair with the extensions configuration. By default we will have the custom extension support return the path of the file that is loaded so you can easily assert that the correct files are loaded. However it's possible that you want to have a custom loader, so you can return something else. The loaders object allows you to provide a mapping between extensions and custom loader files that can be required.

{
  "setup": {
    "loaders": {
      ".css": "css-loader-module-name"
    }
  }
}

And the css-loader-module-name module would export a function that receives a Module instance that it can update with what ever it wants to process.

module.exports = function customloader(Module) {
  Module.exports = require('fs').readFileSync(Module.filename);
}

Debugging

This library makes use of diagnostics to provide debug information incase of unexpected failure when preparing the environment. In order to see these logs you need to start the tests with DEBUG=setup-env*:

DEBUG=setup-env* npm test

License

MIT

indexzero / setup-env