Skip to content

Commit

Permalink
docs: update examples and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ChristopherPHolder
ChristopherPHolder authored Aug 26, 2024
2 parents 0ed1286 + 88b003a commit b8b8f5b
Show file tree
Hide file tree
Showing 39 changed files with 158 additions and 562 deletions.
38 changes: 9 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ In addition, it is always up-to-date with the latest Chrome DevTools features.
- ⚙ [Run it in your CI ](https://github.com/push-based/user-flow#github-workflow-integration-of-lighthouse-user-flows-in-your-pr)
- ▶ [Execute ChromeDevTools recorder exports](https://github.com/push-based/user-flow#working-with-devtools-recorder-exports)
- 🏃‍♀️ Measure Runtime performance
- 🔒 [Performance budgets](https://github.com/push-based/user-flow#performance-budgets)
- 🦮 Zero setup cost
- 🤓 Excellent DX through `--dryRun` and friends
- ⚙ Nx plugin [user-flow-nx-plugin]() to generate/execute/migrate lighthouse user flows
Expand Down Expand Up @@ -103,11 +102,11 @@ _./.user-flowrc.json_
}
```

2. The CLI automatically creates an example user-flow. (`./user-flows/basic-navigation.uf.ts`)
2. 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.ts_
_./basic-navigation.uf.mts_
```typescript
import {
UserFlowInteractionsFn,
Expand All @@ -122,17 +121,15 @@ const interactions: UserFlowInteractionsFn = async (ctx: UserFlowContext): Promi

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

};

const userFlowProvider: UserFlowProvider = {
flowOptions: {name: 'Order Coffee'},
interactions
};

module.exports = userFlowProvider;
export default {
flowOptions: { name: "Order Coffee" },
interactions,
} satisfies UserFlowProvider;
```

3. Run CLI
Expand All @@ -147,7 +144,7 @@ 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](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/writing-basic-user-flows.md) section.

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

```bash
npx user-flow --ufPath=./user-flows-new --outPath=./user-flows-reports --url=https://localhost:4200
Expand Down Expand Up @@ -192,8 +189,6 @@ This command helps you to set up a `.user-flowrc.json` and asks for input over C
| ---------------------------------- | --------- | ---------------------- |----------------------------------------------------------------------------------------------------------|
| **`-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` |
| **`-x`**, **`--generateBudgets`** | `boolean` | n/a | Generate `budget.json` file under the current working directury |
| **`--lhr`** | `string` | n/a | Used together with `--generateBudgets`. Path to lighthouse report for initial budget |

<img width="960" alt="getting-started-resulting-navigation-report" src="https://user-images.githubusercontent.com/10064416/168185483-c6ca499e-a8a6-40b7-b450-448de8784454.PNG">

Expand All @@ -214,9 +209,8 @@ This command executes a set of user-flow definitions against the target URL and
| 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.ts` or`*.uf.js`) |
| **`-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 |
| **`-b`**, **`--budgetPath`** | `string` | n/a | Path to the lighthouse `budget.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`) |
Expand Down Expand Up @@ -279,20 +273,6 @@ This library provides a way to replay and enrich those interactions over the CLI

See [recorder-exports](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/recorder-exports.md) for more details.

## [Performance Budgets](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/performance-budgets.md)

Implementing performance improvements without breaking something is hard.
**Even harder is it, to keep it that way. 🔒**

![img-budgets-mode-support](https://user-images.githubusercontent.com/10064416/164581870-3534f8b0-b7c1-4252-9f44-f07febaa7359.PNG)

Automatically create budgets with:
`npx user-flow init --generateBudgets`
Automatically create budgets from an existing lhr with:
`npx user-flow init --generateBudgets --lhr path/to/lhr.json`

See [performance-budgets](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/performance-budgets.md) for more details.

## [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)

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
Expand Down
10 changes: 4 additions & 6 deletions examples/github-report/user-flows/order-coffee.uf.mts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,7 @@ const interactions: UserFlowInteractionsFn = async (ctx: UserFlowContext): Promi
});
};

const userFlowProvider: UserFlowProvider = {
flowOptions: {name: '☕ Order Coffee ☕'},
interactions
};

module.exports = userFlowProvider;
export default {
flowOptions: { name: '☕ Order Coffee ☕' },
interactions,
} satisfies UserFlowProvider;
1 change: 0 additions & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@
"nx": "nx",
"build-cli": "nx build cli",
"import-graph": "npx @rx-angular/import-graph-visualizer -t packages/cli/tsconfig.lib.json",
"lh": "lighthouse https://example.com --budget-path=./budget.json --output=json --output-path=./lh-inc-budget.json",
"@push-based/user-flow": "npm run build-cli && npx ./dist/packages/cli",
"@push-based/user-flow:help": "npm run @push-based/user-flow -- --help",
"@push-based/user-flow:init": "npm run @push-based/user-flow -- init -v",
Expand Down
27 changes: 3 additions & 24 deletions packages/cli/docs/command-collect.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,7 @@ The result can be stored in different formats or printed in the console.
| Option | Type | Default | Description |
| ---------------------------------- | --------- | ---------------------- |----------------------------------------------------------------------------------------------------------|
| **`-t`**, **`--url`** | `string` | n/a | Value for `collect.url` in your |
| **`-u`**, **`--ufPath`** | `string` | `./user-flows` | Path to user-flow file or folder containg user-flow files to run. (`*.uf.ts` or`*.uf.js`) |
| **`-b`**, **`--budget-path`** | `string` | n/a | Path to the lighthouse `budget.json` file |
| **`-u`**, **`--ufPath`** | `string` | `./user-flows` | Path to user-flow file or folder containg user-flow files to run. (`*.uf.mts` or`*.uf.js`) |
| **`-c`**, **`--config-path`** | `string` | n/a | Path to the lighthouse `config.json` file |
| **`-f`**, **`--format`** | `string` | `html`, `json` setting | Format of the creates reports |
| **`-o`**, **`--outPath`** | `string` | `./measures` | output folder for the user-flow reports |
Expand Down Expand Up @@ -100,7 +99,7 @@ npx user-flow collect --ufPath ./user-flows/spectial-folder
# reference a flow directly
npx user-flow collect --ufPath ./user-flows/spectial-flow.uf.ts
npx user-flow collect --ufPath ./user-flows/spectial-flow.uf.mts
```

**Description:**
Expand All @@ -110,7 +109,7 @@ The path to user-flow file or folder containing user-flows.
You can point to a folder to execute all user flows in there, or execute one file directly.

File formats accepted:
- `*.uf.ts`
- `*.uf.mts`
- `*.js`

### format
Expand Down Expand Up @@ -157,25 +156,6 @@ npx user-flow collect --outPath ./measures
The path to store user-flow reports.
The CLI will automatically create the folder if it does not exist.

### budgetPath

| Option | Type | Default |
| ---------------------------------- | --------- | ---------------------- |
| **`-b`**, **`--budgetPath`** | `string` | n/a |

**Execution:**
```
npx user-flow collect --budgetPath ./budgets.json
```

**Description:**

When used it will parse the given file and uses its content as configuration for budgets in the [LH config](link to docs).

Details on usage and configuration are available in the [lighthouse budgets](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/performance-budgets.md) section.

The `budgets.json` file path can also be placed directly into the rc file under `assert.budgetPath`.

### configPath

| Option | Type | Default |
Expand All @@ -190,7 +170,6 @@ npx user-flow collect --configPath ./lh-config.json
**Description:**
Path to the lighthouse configuration file.
When used it will parse the given file and uses its content as configuration.
If `budgets` are given it will merge them into the existing LH config.

Details on usage and configuration are available in the [lighthouse configuration](https://github.com/push-based/user-flow/blob/main/packages/cli/docs/lighthouse-configuration.md) section.

Expand Down
42 changes: 4 additions & 38 deletions packages/cli/docs/command-init.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,11 @@ In addition, it helps to do scaffolding by create basic files and folders needed
| Option | Type | Default | Description |
| ---------------------------------- | --------- | ---------------------- |----------------------------------------------------------------------------------------------------------|
| **`-t`**, **`--url`** | `string` | n/a | Value for `collect.url` in your |
| **`-u`**, **`--ufPath`** | `string` | `./user-flows` | Path to user-flow file or folder containg user-flow files to run. (`*.uf.ts` or`*.uf.js`) |
| **`-u`**, **`--ufPath`** | `string` | `./user-flows` | Path to user-flow file or folder containg user-flow files to run. (`*.uf.mts` or`*.uf.js`) |
| **`-o`**, **`--outPath`** | `string` | `./measures` | output folder for the user-flow reports |
| **`-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 |
| **`-b`**, **`--budget-path`** | `string` | n/a | Path to the lighthouse `budget.json` file |
| **`-c`**, **`--config-path`** | `string` | n/a | Path to the lighthouse `config.json` file |

**Options file scaffolding:**
Expand All @@ -41,9 +40,6 @@ In addition, it helps to do scaffolding by create basic files and folders needed
| ------------------------------------ | --------- | ---------------------- |----------------------------------------------------------------------------------------------------------|
| **`-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` |
| **`-x`**, **`--generateBudgets`** | `boolean` | n/a | Generate `budget.json` file under the current working directury |
| **`--lhr`** | `string` | n/a | Used together with `--generateBudgets`. Path to lighthouse report for initial budget |


## Options related to the `user-flowrc.json` file

Expand Down Expand Up @@ -99,10 +95,10 @@ npx user-flow init --no-generateFlow

**Description:**

If the `init` command is executed with `--generateFlow` it will generate a file named `basic-navigation.uf.ts`.
If the `init` command is executed with `--generateFlow` it will generate a file named `basic-navigation.uf.mts`.
It contains a basic user flow and will be placed in the folder configured in you `.user-flowrc.json` file for `collect.ufPath`.

The `basic-navigation.uf.ts` template can be found [here](https://github.com/push-based/user-flow/blob/ba6a8d4fbf8060bea067e0fa3528611be5653ddf/packages/cli/src/lib/commands/init/static/basic-navigation.uf.ts#L2)
The `basic-navigation.uf.mts` template can be found [here](https://github.com/push-based/user-flow/blob/ba6a8d4fbf8060bea067e0fa3528611be5653ddf/packages/cli/src/lib/commands/init/static/basic-navigation.uf.mts#L2)

If the `init` command executes with `--no-generateFlow` nothing will be created nor prompted in the console.

Expand All @@ -126,40 +122,10 @@ npx user-flow init --no-generateGhWorkflow
If the `init` command is executed with `--generateGhWorkflow` it will generate a file named `user-flow-ci.yml`.
It contains a basic workflow to execute the CLI in GitHubs pipe line.

The `user-flow-ci.yml` template can be found [here](https://github.com/push-based/user-flow/blob/ba6a8d4fbf8060bea067e0fa3528611be5653ddf/packages/cli/src/lib/commands/init/static/basic-navigation.uf.ts#L2)
The `user-flow-ci.yml` template can be found [here](https://github.com/push-based/user-flow/blob/ba6a8d4fbf8060bea067e0fa3528611be5653ddf/packages/cli/src/lib/commands/init/static/basic-navigation.uf.mts#L2)

If the `init` command executes with `--no-generateGhWorkflow` nothing will be created nor prompted in the console.

### generateBudgets & lhr

| Option | Type | Default |
| ------------------------------------ | --------- | ---------------------- |
| **`-x`**, **`--generateBudgets`** | `boolean` | n/a |
| **`--lhr`** | `string` | n/a |

**Execution:**
```
npx user-flow init --generateBudgets
# or as negation
npx user-flow init --no-generateBudgets
# or to derive budgets form an existing lighthouse report
npx user-flow init --generateBudgets --lhr path/to/lhr.json
```

**Description:**

If the `init` command is executed with `--generateBudgets` it will generate a file named `budgets.json`.
It contains basic lighthouse budgets to be used in the rc file or CLI.

If the `init` command executes with `--no-generateBudgets` nothing will be created nor prompted in the console.

Automatically derive budgets from a report:
If the `init` command executes with `--generateBudgets` and `--lhr=path/to/lhr.json` the budgets will be derived from the given lighthouse report.

---

made with ❤ by [push-based.io](https://www.push-based.io)
2 changes: 1 addition & 1 deletion packages/cli/docs/general-cli-features.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ A function that logs the passed string only if the CIL options `--verbose` or `-

**Usage**

_./order-coffee.uf.ts_
_./order-coffee.uf.mts_
```typescript
import { logVerbose } from "@push-based/user-flow";
// ...
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/docs/github-workflow-integration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ In this document we will learn:
## Setup user flow for the CI

As pre-condition we assume you have a correct setup of the CLI as descried in [basic setup](writing-basic-user-flows.md).
This means you have a `user-flowrc.json` to point to as well as a `flow-name.ts` to execute.
This means you have a `user-flowrc.json` to point to as well as a `flow-name.mts` to execute.

To test if you flow is working quickly run the CLI in 'dry run' and print it to the console to see the test passes:
`user-flow collect --dryRun --format stdout` optionally use `--rcPath /path/to/user-flowrc.json` if the rc file is not located in root.
Expand Down
Loading

0 comments on commit b8b8f5b

Please sign in to comment.