@push-based/user-flow

Runtime performance measurements done right, with Lighthouse user flows!

This is a library & CLI to organize and run Lighthouse user flows in an organized and scalable way 🛸 with CI automation in place

What is it?

A CLI tool to measure performance continuously and also integrate it into your CI. It provides lot's of DX features, nice commands with rich arguments and integration with the latest dev tooling.

Why to use it?

It will enable you to measure bootstrap as well as runtime performance with minimum effort, speed up your performance test development and reduced the needed code and configuration to a minimum.

In addition, it is always up-to-date with the latest Chrome DevTools features.

Benefits

⚙ Run it in your CI
▶ Execute ChromeDevTools recorder exports
🏃‍♀️ Measure Runtime performance
🦮 Zero setup cost
🤓 Excellent DX through --dryRun and friends
⚙ Nx plugin user-flow-nx-plugin to generate/execute/migrate lighthouse user flows
🛸 Advanced architecture with UFO's
🔥 Write tests directly in TypeScript (we compile them live)
🧠 Use best practices out of the box
🅾 No boilerplate

Install

Run npm i @push-based/user-flow --save-dev or yarn add @push-based/user-flow --dev to install the library.

After that you can run:
user-flow --helpor user-flow --help

Run without install

You can also use npx to run it in e.g. the CI setup: npx @push-based/user-flow --help

Quick Start

As the CLI needs a npm project to run in we explain 2 common things, using the package in an existing project and using it in a fresh project. Both ways require a node and npm project setup to install user-flow and folders to store the reports and test files.

have node v14.X.X installed
run node -v and npm -v to check it.

To start from scratch read setup an empty project

Set up and run user flows in an existing npm project

In this chapter we will learn how to install and configure user flows, as well as create a first example test and see the resulting performance report.

Install:

npm i @push-based/user-flow --save-dev

Set up the .user-flowrc.json config file

Run

npx @push-based/user-flow init

or if you already installed it,

npx user-flow init

in the console and accept the default value for every question.

This results in the following file:

./.user-flowrc.json

{
  "collect": {
    "url": "https://coffee-cart.netlify.app/",
    "ufPath": "./user-flows"
  },
  "persist": { "outPath": "./measures", "format": ["html"] }
}

The CLI automatically creates an example user-flow. (./user-flows/basic-navigation.uf.mts)

It is a simple navigation measurement to start from.

./basic-navigation.uf.mts

import {
  UserFlowInteractionsFn,
  UserFlowContext,
  UserFlowProvider
} from '@push-based/user-flow';

// Your custom interactions with the page 
const interactions: UserFlowInteractionsFn = async (ctx: UserFlowContext): Promise<any> => {
  const { page, flow, browser, collectOptions } = ctx;
  const { url } = collectOptions;

  // Navigate to URL
  await flow.navigate(url, {
    name: `Navigate to ${url}`,
  });

};

export default {
  flowOptions: { name: "Order Coffee" },
  interactions,
} satisfies UserFlowProvider;

Run CLI You can directly run the cli command. The typescript files will get resolved and compiled live.

npx user-flow collect or just npx user-flow as collect is the default.

This will execute the user flow and opens the HTML report in the browser:

For more information on how to write user-flows read in the Writing user flows for the CLI section.

Optionally you can pass params to overwrite the values form .user-flowrc.json in the file directly or over the CLI:

npx user-flow --ufPath=./user-flows-new --outPath=./user-flows-reports --url=https://localhost:4200

🤓 DX Tip:
For a faster development process you can use the --dryRun option to skip measurement and perform the interactions only
This is a multitude faster e.g. 3s vs 53s for a simple 2 step flow with navigation

CLI

You can read more about tricks and DX the general CLI features in our docs.

Global Options

Option	Type	Default	Description
`--help`, `-h`	`boolean`	`undefined`	Show help
`--version`	`boolean`	`undefined`	Show version number of cli
`--rcPath`, `-p`	`string`	`./user-flowrc.json`	Path to user-flow.config.json. e.g. `./user-flowrc.json`
`--verbose`, `-v`	`boolean`	`undefined`	Run with verbose logging
`--interactive` `-i`	`boolean`	`true` (`false` in CI mode)	When false questions are skipped with the values from the suggestions. This is useful for CI integrations.

Commands

`*` command

Run the default command over:
@npx @push-based/user-flow [options]

Description:
The default command forwards all options to the collect command.

`init` command

Run command over:
@npx @push-based/user-flow init [options]

Description:
This command helps you to set up a .user-flowrc.json and asks for input over CLI prompts.

Option	Type	Default	Description
`-h`, `--generateFlow`	`boolean`	n/a	Generate basic user-flow file under `ufPath`
`-g`, `--generateGhWorkflow`	`boolean`	n/a	Generate `user-flow.yml` file under `.github/workflows`

As a result we get a .user-flowrc.json and an example flow if answered with yes.

🤓 DX Tip: Set up user flows in a sub directory:
npx @push-based/user-flow init --rcPath ./path/to/project/.user-flowrc.json

`collect` command

Run command over:
@npx @push-based/user-flow collect [options] or @npx @push-based/user-flow [options] as it is the default command.

Description:
This command executes a set of user-flow definitions against the target URL and saves the output.

Option	Type	Default	Description
`-t`, `--url`	`string`	n/a	URL to analyze
`-u`, `--ufPath`	`string`	`./user-flows`	Path to user-flow file or folder containing user-flow files to run. (`.uf.mts` or`.uf.js`)
`-c`, `--configPath`	`string`	n/a	Path to the lighthouse `config.json` file
`-s`, `--serveCommand`	`string`	n/a	Runs a npm script to serve the target app. This has to be used in combination with `--awaitServeStdout`
`-a`, `--awaitServeStdout`	`string`	`.user-flowrc` setting	Waits for stdout from the serve command to start collecting user-flows
`-f`, `--format`	`string`	`html`, `json` setting	Format of the creates reports ( `html`, `json`, `md`, `stdout`)
`-o`, `--outPath`	`string`	`./measures`	output folder for the user-flow reports
`-e`, `--openReport`	`boolean`	`true`	Opens file automatically after the user-flow is captured
`-d`, `--dryRun`	`boolean`	`false`	When true the user-flow test will get executed without measures (for fast development)

💡 Pro Tip: CLI arguments that accept multiple values can be set by using the param multiple times in a row:

As an example we could apply two different formats as output for the collect command: npx user-flow collect --format=json --format=md

Configuration

The CLI supports the official user-flow/lighthouse configuration.

Details on how to work with configurations can be found in the configuratin section.

Writing user flows for the CLI

You can think of user flows as front end e2e tests which measures performance related information during the test.

Basic user flows

Write basic user flows leveraging all 3 measurement modes of lighthouse.

User flow measurement modes

Mode	Measure	Performance	Accessibility	Best Practices	SEO	PWA
Navigation	Page load	100% / 30	100% / 30	100% / 30	100% / 30	✔ / 7
Timespan	User Interaction	10 / 10	❌	7 / 7	❌	❌
Snapshot	Current page state	4 / 4	16 / 16	5 / 5	9 / 9	❌

When you execute and open the user-flow report you will see the measurement modes also visualized there.

Advanced architecture

Organizing testing logic is an art. If you don't own that knowledge, the amount of low-level code get's a night mare to maintain in bigger projects...

This is the reason we introduced UFO's! Organize clutter code 👽 in developer friendly shells 🛸

See ufo-architecture for more details.

Working with DevTools Recorder exports

Chrome DevTools provides a feature to help with record and export user interactions. This can replace any handwritten code and organizes interactions in a JSON structure.

This library provides a way to replay and enrich those interactions over the CLI.

See recorder-exports for more details.

GitHub workflow integration of lighthouse user flows in your PR

With just a few steps you can run your user flows in as a GitHub workflow to enrich your PR's with report summaries as comments.

Automatically create a workflow with:
npx user-flow init --generateGhWorkflow

See github-workflow-integration for more details.

Nx workspace integration of lighthouse user flows as nx-plugin

With just a few steps you can run your user flows in as a Nx workspace to enrich your DX with a nx-plugin.

Automatically generate/execute/migrate with user-flow-nx-plugin:

nx g @push-based/user-flow-nx-plugin:install
nx g @push-based/user-flow-nx-plugin:target e2e

See user-flow-nx-plugin for more details.

Examples

angular-movies

Resources

lighthouse viewer
Understanding the lighthouse result
lighthouse user flows
lighthouse user flow recorder
lighthouse user flow recorder features

made with ❤ by push-based.io

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

@push-based/user-flow

Runtime performance measurements done right, with Lighthouse user flows!

This is a library & CLI to organize and run Lighthouse user flows in an organized and scalable way 🛸 with CI automation in place

What is it?

Why to use it?

Install

Run without install

Quick Start

Set up and run user flows in an existing npm project

CLI

Global Options

Commands

`*` command

`init` command

`collect` command

Configuration

Writing user flows for the CLI

Basic user flows

Advanced architecture

Working with DevTools Recorder exports

GitHub workflow integration of lighthouse user flows in your PR

Nx workspace integration of lighthouse user flows as nx-plugin

Examples

Resources

Files

README.md

Latest commit

History

README.md

File metadata and controls

@push-based/user-flow

Runtime performance measurements done right, with Lighthouse user flows!

This is a library & CLI to organize and run Lighthouse user flows in an organized and scalable way 🛸 with CI automation in place

What is it?

Why to use it?

Install

Run without install

Quick Start

Set up and run user flows in an existing npm project

CLI

Global Options

Commands

* command

init command

collect command

Configuration

Writing user flows for the CLI

Basic user flows

Advanced architecture

Working with DevTools Recorder exports

GitHub workflow integration of lighthouse user flows in your PR

Nx workspace integration of lighthouse user flows as nx-plugin

Examples

Resources

`*` command

`init` command

`collect` command