{"id":13603237,"url":"https://github.com/push-based/user-flow","last_synced_at":"2025-04-13T04:09:36.587Z","repository":{"id":36960903,"uuid":"465735273","full_name":"push-based/user-flow","owner":"push-based","description":"📦 Combine Chrome tooling like Lighthouse userflows and DevTools reconder scripts in your CI","archived":false,"fork":false,"pushed_at":"2024-09-23T10:55:57.000Z","size":17620,"stargazers_count":122,"open_issues_count":22,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-13T04:09:23.099Z","etag":null,"topics":["chrome","cli","devtools","lighthouse-audits","performance-analysis","performance-metrics","performance-monitoring","performance-testing","pupeteer","typescript","web-performance"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/push-based.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["push-based","BioPhoton"]}},"created_at":"2022-03-03T13:42:17.000Z","updated_at":"2025-04-08T23:45:04.000Z","dependencies_parsed_at":"2024-01-25T21:30:32.184Z","dependency_job_id":"3eac6ac4-f024-4e43-b634-16e2c7d1a3d7","html_url":"https://github.com/push-based/user-flow","commit_stats":{"total_commits":1324,"total_committers":10,"mean_commits":132.4,"dds":0.31797583081571,"last_synced_commit":"e8d2039c3c7de1963288bf09259222395061e1da"},"previous_names":[],"tags_count":159,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/push-based%2Fuser-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/push-based%2Fuser-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/push-based%2Fuser-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/push-based%2Fuser-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/push-based","download_url":"https://codeload.github.com/push-based/user-flow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248661704,"owners_count":21141450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chrome","cli","devtools","lighthouse-audits","performance-analysis","performance-metrics","performance-monitoring","performance-testing","pupeteer","typescript","web-performance"],"created_at":"2024-08-01T18:01:58.442Z","updated_at":"2025-04-13T04:09:36.563Z","avatar_url":"https://github.com/push-based.png","language":"HTML","funding_links":["https://github.com/sponsors/push-based","https://github.com/sponsors/BioPhoton"],"categories":["HTML","cli"],"sub_categories":[],"readme":"# @push-based/user-flow\n## Runtime performance measurements done right, with Lighthouse user flows!\n\n[![npm](https://img.shields.io/npm/v/%40push-based%2Fuser-flow.svg)](https://www.npmjs.com/package/%40push-based%2Fuser-flow)\n\n---\n\n### This is a library \u0026 CLI to organize and run Lighthouse user flows in an organized and scalable way 🛸 with CI automation in place\n\n---\n\n# What is it?\n\nA CLI tool to measure performance continuously and also integrate it into your CI.\nIt provides lot's of DX features, nice commands with rich arguments and integration with the latest dev tooling. \n\n# Why to use it?\n\nIt will enable you to measure bootstrap as well as runtime performance with minimum effort, \nspeed up your performance test development and reduced the needed code and configuration to a minimum. \n\n![user-flow-code-reduction](https://user-images.githubusercontent.com/10064416/197062344-4c49c73b-beed-4a7e-92f9-c4855e9f436d.PNG)\n\nIn addition, it is always up-to-date with the latest Chrome DevTools features.\n\n**Benefits**\n\n- ⚙ [Run it in your CI  ](https://github.com/push-based/user-flow#github-workflow-integration-of-lighthouse-user-flows-in-your-pr)  \n- ▶ [Execute ChromeDevTools recorder exports](https://github.com/push-based/user-flow#working-with-devtools-recorder-exports)  \n- 🏃‍♀️ Measure Runtime performance\n- 🦮 Zero setup cost\n- 🤓 Excellent DX through `--dryRun` and friends\n- ⚙ Nx plugin [user-flow-nx-plugin]() to generate/execute/migrate lighthouse user flows\n- 🛸 [Advanced architecture with UFO's](https://github.com/push-based/user-flow#advanced-architecture)\n- 🔥 Write tests directly in TypeScript (we compile them live)\n- 🧠 Use best practices out of the box\n- 🅾 No boilerplate\n\n\n\u003cimg src=\"https://user-images.githubusercontent.com/10064416/156827417-1e9979a2-83ea-4117-baec-9b7ce81ab811.png\" aspecrratio=\"885∶254\" width=\"400px\" height=\"auto\"/\u003e\n\n# Install\n\nRun \n`npm i @push-based/user-flow --save-dev` or `yarn add @push-based/user-flow --dev` \nto install the library.  \n  \nAfter that you can run:  \n`user-flow --help`or `user-flow --help`  \n\n## Run without install\nYou can also use `npx` to run it in e.g. the CI setup:\n`npx @push-based/user-flow --help`\n \n# Quick Start\n\nAs 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.\nBoth ways require a node and npm project setup to install user-flow and folders to store the reports and test files.\n\n0. have node [v14.X.X](https://nodejs.org/en/download/) installed  \nrun `node -v` and `npm -v` to check it.  \n\nTo start from scratch read [setup an empty project](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/general-cli-features.md)\n\n## Set up and run user flows in an existing npm project \n\nIn 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.  \n\n0. Install:\n\n```bash\nnpm i @push-based/user-flow --save-dev\n```\n\n1. Set up the `.user-flowrc.json` config file\n\nRun \n```\nnpx @push-based/user-flow init\n```  \n\nor if you already installed it,\n\n```\nnpx user-flow init\n```  \n\nin the console and accept the default value for every question.\n\n![Set up user-flow in existing project gif](./docs/images/setup-in-existing-project.gif)\n\nThis results in the following file:\n\n_./.user-flowrc.json_\n```json\n{\n  \"collect\": {\n    \"url\": \"https://coffee-cart.netlify.app/\",\n    \"ufPath\": \"./user-flows\"\n  },\n  \"persist\": { \"outPath\": \"./measures\", \"format\": [\"html\"] }\n}\n```\n\n2. The CLI automatically creates an example user-flow. (`./user-flows/basic-navigation.uf.mts`) \n\nIt is a simple navigation measurement to start from.\n\n_./basic-navigation.uf.mts_\n```typescript\nimport {\n  UserFlowInteractionsFn,\n  UserFlowContext,\n  UserFlowProvider\n} from '@push-based/user-flow';\n\n// Your custom interactions with the page \nconst interactions: UserFlowInteractionsFn = async (ctx: UserFlowContext): Promise\u003cany\u003e =\u003e {\n  const { page, flow, browser, collectOptions } = ctx;\n  const { url } = collectOptions;\n\n  // Navigate to URL\n  await flow.navigate(url, {\n    name: `Navigate to ${url}`,\n  });\n\n};\n\nexport default {\n  flowOptions: { name: \"Order Coffee\" },\n  interactions,\n} satisfies UserFlowProvider;\n```\n\n3. Run CLI\nYou can directly run the cli command. The typescript files will get resolved and compiled live. \n\n`npx user-flow collect` or just `npx user-flow` as collect is the default.\n\nThis will execute the user flow and opens the HTML report in the browser:\n\n\u003cimg width=\"960\" alt=\"getting-started-resulting-navigation-report\" src=\"https://user-images.githubusercontent.com/10064416/168185483-c6ca499e-a8a6-40b7-b450-448de8784454.PNG\"\u003e\n\n\nFor more information on how to write user-flows read in the [Writing user flows for the CLI](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/writing-basic-user-flows.md) section.\n\nOptionally you can pass params to overwrite the values form `.user-flowrc.json` in the file directly or over the CLI:\n\n```bash\nnpx user-flow --ufPath=./user-flows-new --outPath=./user-flows-reports --url=https://localhost:4200\n```\n  \n\u003e **🤓 DX Tip:**  \n\u003e For a faster development process you can use the `--dryRun` option to skip measurement and perform the interactions only  \n\u003e This is a multitude faster e.g. **3s** vs **53s** for a simple 2 step flow with navigation  \n\n# CLI\nYou can read more about tricks and DX the [general CLI features](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/general-cli-features.md) in our docs. \n\n## Global Options\n\n| Option                       |  Type     | Default                     |  Description                                                                                               |  \n|------------------------------| --------- | --------------------------- |----------------------------------------------------------------------------------------------------------- |  \n| **`--help`**, **`-h`**       | `boolean` | `undefined`                 | Show help                                                                                                  |  \n| **`--version`**              | `boolean` | `undefined`                 | Show version number of cli                                                                                 |  \n| **`--rcPath`**, **`-p`**     | `string`  | `./user-flowrc.json`        | Path to user-flow.config.json. e.g. `./user-flowrc.json`                                                   |  \n| **`--verbose`**, **`-v`**    | `boolean` | `undefined`                 | Run with verbose logging                                                                                   |  \n| **`--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. |  \n\n## Commands \n\n### `*` command\n\nRun the default command over:  \n`@npx @push-based/user-flow [options]`  \n\nDescription:  \nThe default command forwards all options to the [`collect`](https://github.com/push-based/user-flow#collect-command) command.\n\n### [`init` command](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/command-init.md)\n\nRun command over:  \n`@npx @push-based/user-flow init [options]`  \n\nDescription:  \nThis command helps you to set up a `.user-flowrc.json` and asks for input over CLI prompts.\n\n|  Option                            |  Type     | Default                | Description                                                                                              |  \n| ---------------------------------- | --------- | ---------------------- |----------------------------------------------------------------------------------------------------------|  \n| **`-h`**, **`--generateFlow`**     | `boolean` | n/a                    | Generate basic user-flow file under `ufPath`                                                             |    \n| **`-g`**, **`--generateGhWorkflow`** | `boolean` | n/a                  | Generate `user-flow.yml` file under `.github/workflows`                                                             |    \n\n\u003cimg width=\"960\" alt=\"getting-started-resulting-navigation-report\" src=\"https://user-images.githubusercontent.com/10064416/168185483-c6ca499e-a8a6-40b7-b450-448de8784454.PNG\"\u003e\n\nAs a result we get a `.user-flowrc.json` and an example flow if answered with yes.\n\n\u003e **🤓 DX Tip:** \n\u003e Set up user flows in a sub directory:  \n\u003e `npx @push-based/user-flow init --rcPath ./path/to/project/.user-flowrc.json`\n\n### [`collect` command](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/command-collect.md)\n\nRun command over:  \n`@npx @push-based/user-flow collect [options]`  or `@npx @push-based/user-flow [options]` as it is the default command.  \n\nDescription:  \nThis command executes a set of user-flow definitions against the target URL and saves the output.\n\n| Option                             | Type      | Default                | Description                                                                                             |  \n|------------------------------------|-----------|------------------------|---------------------------------------------------------------------------------------------------------|  \n| **`-t`**, **`--url`**              | `string`  | n/a                    | URL to analyze                                                                                          |  \n| **`-u`**, **`--ufPath`**           | `string`  | `./user-flows`         | Path to user-flow file or folder containing user-flow files to run. (`*.uf.mts` or`*.uf.js`)            |  \n| **`-c`**, **`--configPath`**       | `string`  | n/a                    | Path to the lighthouse `config.json` file                                                               |  \n| **`-s`**, **`--serveCommand`**     | `string`  | n/a                    | Runs a npm script to serve the target app. This has to be used in combination with `--awaitServeStdout` |  \n| **`-a`**, **`--awaitServeStdout`** | `string`  | `.user-flowrc` setting | Waits for stdout from the serve command to start collecting user-flows                                  |  \n| **`-f`**, **`--format`**           | `string`  | `html`, `json` setting | Format of the creates reports ( `html`, `json`, `md`, `stdout`)                                         |  \n| **`-o`**, **`--outPath`**          | `string`  | `./measures`           | output folder for the user-flow reports                                                                 |  \n| **`-e`**, **`--openReport`**       | `boolean` | `true`                 | Opens file automatically after the user-flow is captured                                                |  \n| **`-d`**, **`--dryRun`**           | `boolean` | `false`                | When true the user-flow test will get executed without measures (for fast development)                  |  \n\n\u003e **💡 Pro Tip:**\n\u003e CLI arguments that accept multiple values can be set by using the param multiple times in a row:\n\u003e\n\u003e As an example we could apply two different formats as output for the `collect` command:\n\u003e `npx user-flow collect --format=json --format=md`\n\n## Configuration\n\nThe CLI supports the official [user-flow/lighthouse configuration](https://github.com/GoogleChrome/lighthouse/blob/master/docs/configuration.md). \n\nDetails on how to work with configurations can be found in the [configuratin section](./packages/cli/docs/lh-configuraton.md).    \n\n\n# Writing user flows for the CLI\n\nYou can think of user flows as front end e2e tests which measures performance related information during the test.\n\n## [Basic user flows](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/writing-basic-user-flows.md)\n\nWrite basic user flows leveraging all 3 measurement modes of lighthouse.\n\n\n**User flow measurement modes**\n\n| Icon  | Mode       | Measure            | Performance  | Accessibility | Best Practices | SEO       | PWA       |\n| ----- | ---------- | ------------------ | ------------ | ------------- | -------------- | --------- | --------- |\n| ![user-flow_navigation-icon](https://user-images.githubusercontent.com/10064416/165129388-2f62bb82-4856-456c-a513-ae5607cfe4ea.PNG) | Navigation | Page load          | 100% / 30    | 100% / 30     | 100% / 30      | 100% / 30 | ✔ / 7 |\n| ![user-flow_timespan-icon](https://user-images.githubusercontent.com/10064416/165129495-330ddca5-fd8b-4ecc-a839-477302f7f229.PNG) | Timespan   | User Interaction   |  10  / 10    |       ❌      |   7  /  7      |     ❌    |     ❌    |\n| ![user-flow_snapshot-icon](https://user-images.githubusercontent.com/10064416/165129696-68302177-6c7d-4aa2-ba3c-564939cde228.PNG) | Snapshot   | Current page state |   4  /  4    |  16  / 16     |   5  /  5      |   9  /  9 |     ❌    |\n\nWhen you execute and open the user-flow report you will see the measurement modes also visualized there.\n\n[![user-flow--example](https://user-images.githubusercontent.com/10064416/166849157-f1d799f5-1f05-481b-8234-ec6645827791.PNG)](https://github.com/push-based/user-flow/blob/main/packages/cli/README.md)\n\n## [Advanced architecture](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/ufo-architecture.md)\n\nOrganizing 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...\n\n**This is the reason we introduced UFO's!**\n**Organize clutter code 👽 in developer friendly shells 🛸**\n\n![user-flow--advanced-architecture](https://user-images.githubusercontent.com/10064416/208248762-504897a3-3ef5-42dc-8060-70cda0ad682f.PNG)\n\nSee [ufo-architecture](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/ufo-architecture.md) for more details.\n\n## [Working with DevTools Recorder exports](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/recorder-exports.md)\n\nChrome DevTools provides a feature to help with record and export user interactions. \nThis can replace any handwritten code and organizes interactions in a JSON structure.\n![user-flow--replay-scripts](https://user-images.githubusercontent.com/10064416/208249076-744bc6be-aa03-42f7-b209-c815c2f90ca2.PNG)\n\nThis library provides a way to replay and enrich those interactions over the CLI.\n\nSee [recorder-exports](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/recorder-exports.md) for more details.\n\n## [GitHub workflow integration of lighthouse user flows in your PR](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/github-workflow-integration.md)\n\nWith just a few steps you can run your user flows in as a GitHub workflow to enrich your PR's with report summaries as\ncomments.\n\nAutomatically create a workflow with:  \n`npx user-flow init --generateGhWorkflow`\n\n![user-flow-gh-action-cover](https://user-images.githubusercontent.com/10064416/216605948-b8fffdda-3459-48c9-975a-75ec95544d30.png)\n\nSee [github-workflow-integration](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/github-workflow-integration.md)\nfor more details.\n\n## [Nx workspace integration of lighthouse user flows as nx-plugin](https://github.com/push-based/user-flow/blob/main/packages/user-flow-nx-plugin/Readme.md)\n\nWith just a few steps you can run your user flows in as a Nx workspace to enrich your DX with a nx-plugin.\n\nAutomatically generate/execute/migrate with `user-flow-nx-plugin`:\n\n- `nx g @push-based/user-flow-nx-plugin:install`\n- `nx g @push-based/user-flow-nx-plugin:target e2e`\n\nSee [user-flow-nx-plugin](https://github.com/push-based/user-flow/blob/main/packages/user-flow-nx-plugin/Readme.md) for\nmore details.\n\n## Examples\n\n- [angular-movies](https://github.com/tastejs/angular-movies/tree/main/projects/movies-user-flows/src)\n\n## Resources\n\n- [lighthouse viewer](https://googlechrome.github.io/lighthouse/viewer/)\n- [Understanding the lighthouse result](https://github.com/GoogleChrome/lighthouse/blob/master/docs/understanding-results.md)\n- [lighthouse user flows](https://web.dev/lighthouse-user-flows/)\n- [lighthouse user flow recorder](https://developer.chrome.com/docs/devtools/recorder/)\n- [lighthouse user flow recorder features](https://m.youtube.com/watch?v=PupwBARjaYU\u0026feature=youtu.be)\n\n---\n\nmade with ❤ by [push-based.io](https://www.push-based.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpush-based%2Fuser-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpush-based%2Fuser-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpush-based%2Fuser-flow/lists"}