Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update examples and docs #281

Merged
merged 4 commits into from
Aug 26, 2024
Merged

docs: update examples and docs #281

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3ea4393
fix(workspace): update examples and docs
ChristopherPHolder Aug 26, 2024
e3fa1d9
fix(workspace): update examples and docs
ChristopherPHolder Aug 26, 2024
a5bb40f
fix(workspace): fix test
ChristopherPHolder Aug 26, 2024
88b003a
fix(workspace): fix test
ChristopherPHolder Aug 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 9 additions & 29 deletions README.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading