umu

WIP: Execute uvu tests in real browser environments

Important: Currently only playwright is supported (WIP)! Important: The playwright and/or puppeteer APIs are not (currently) accessible to your test code.

Usage

Unlike uvu, the umu CLI is required (for now). The umu CLI manages browser orchestration, test bundling, and test execution.

Let's take a look at the CLI's help text:

$ umu --help
#
#   Usage
#     $ umu [dir] [pattern] [options]
#
#   Options
#     -C, --cwd         The current directory to resolve from  (default .)
#     -b, --bail        Exit on first failure
#     -i, --ignore      Any file patterns to ignore
#     -r, --require     Additional module(s) to preload
#     -B, --browser     The browser engine to launch. Must be one of "chromium", "firefox", or "webkit".  (default chromium)
#     -c, --coverage    Gather coverage information for source files. Requires "chromium" browser.
#     -d, --devtools    Open the Developer Tools panel. Requires "chromium" browser.
#     -H, --headless    Runs the browser in headless mode.  (default true)
#     -v, --version     Displays current version
#     -h, --help        Displays this message
#

If you're familiar with uvu, you'll notice that this is familiar. By design, the umu CLI is backwards compatible with the uvu CLI. This means that you can replace any previous instances of uvu with umu and your tests will automagically run inside a browser!

-$ uvu packages test -i fixtures -r ts-node/register
+$ umu packages test -i fixtures -r ts-node/register

You can customize the browser selection (playwright only) or browser execution settings through the additional option flags that umu brings.

Bundling

TODO:: This may become an optional step (See #3)

After matching test files, umu bundles each test file individually via Rollup. By default, umu includes the bare minimum amount of Rollup configuration so that your tests can be executed within the browser. This includes:

• Producing a single-file bundle
• Inlining all import and require statements
• Replacing references to process.env, process.env.NODE_ENV, and process.browser
• Including an inline source map

Any further customization – for example, defining import aliases, custom transforms, etc – must be handled through the umu.config.js file. Please see Config for more information.

Config

TODO: The format/keys will most likely change (See #2)

When defined, a umu.config.js file must export a function. It will receive two parameters:

• config — the WIP Rollup configuration object
• options — an object of options for a set of included Rollup plugins:
  • options.resolve — options for @rollup/plugin-node-resolve
  • options.commonjs — options for @rollup/plugin-commonjs
  • options.replace — options for @rollup/plugin-replace

Your function must mutate config (and options optionally) in order to produce a satisfactory Rollup configuration. The plugins tied to options are pushed into config.plugins for you.

Important: The config.output.format and config.output.sourcemap values are controlled.

Locations

A umu.config.js file can be defined anywhere that is accessible to your process.cwd() location.

Typically, you'll only ever need one configuration file per project, but there may be times where you need multiple configuration files per directory/workspace. In these cases, a configuration file will be automatically loaded depending on where umu is invoked.

Let's assume this project structure:

my-library
  ├── package.json
  ├── umu.config.js
  └── packages
    └── hello
      ├── umu.config.js
      └── test
        └── ...
    └── world
      └── test
        └── ...

And then let's assume we run the following commands from the project root (my-library):

$ umu packages test
#=> "hello" tests use `my-library/umu.config.js` (root)
#=> "world" tests use `my-library/umu.config.js` (root)

$ umu test --cwd packages/hello
#=> "hello" tests use `my-library/packages/hello/umu.config.js` (scoped)

$ umu test --cwd packages/world
#=> "world" tests use `my-library/umu.config.js` (root)

License

MIT © Luke Edwards