umu
WIP: Execute
uvu
tests in real browser environments
Important: Currently only
playwright
is supported (WIP)! Important: Theplaywright
and/orpuppeteer
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
andrequire
statements - Replacing references to
process.env
,process.env.NODE_ENV
, andprocess.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
andconfig.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