From daaa7e4bd61a9f1a3a331c2c549d49d9f94d9b92 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Wed, 10 Jul 2024 14:01:16 -0700 Subject: [PATCH] chore: cmd readme [skip ci] --- packages/cmd/README.md | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/packages/cmd/README.md b/packages/cmd/README.md index f731763..979d5ac 100644 --- a/packages/cmd/README.md +++ b/packages/cmd/README.md @@ -1,6 +1,6 @@ # @currents/cmd -CLI tools for [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting, and analyzing parallel CI tests. +CLI tool for [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting, and analyzing CI tests. ## Installation @@ -10,27 +10,27 @@ npm install @currents/cmd --save-dev ## Usage -Run the CLI command: +- Generate test results with one of the reporters (see [documentation](https://docs.currents.dev) for the list of supporter reporters) +- Upload the results ```sh npx currents upload --project-id=xxx --key=yyy ``` -The command will: +ℹī¸ Get familiar with [CI Build ID 📖](https://docs.currents.dev/guides/ci-build-id) (`--ci-build-id`) before using the tool in CI. -1. Read the configuration. +## Notes - The report directory is determined from `process.env.CURRENTS_REPORT_DIR` or `--reportDir`, or the most recently created directory named using the pattern `.currents-report-[timestamp]-[uuidv4()]` in the current working directory. +Obtain `--project-id` and [--key](https://docs.currents.dev/guides/record-key) from https://app.currents.dev to identify the project and associate the results with your organization. - The report directory contains test results grouped by spec file and the configuration information used to obtain them. +`currents` will upload the results, as follows: -2. Optionally run a full test suite "discovery" process, which will try to find all tests (required for the Currents platform). +- use `process.env.CURRENTS_REPORT_DIR` or `--reportDir` to read the results previosly generated by one of supported reporters, otherwise +- use the most recently created directory named as `.currents-report-[timestamp]-[uuidv4()]` in the current working directory - The full test suite includes the tests that should be part of the same run but executed across different machines. +> ℹī¸ Get familiar with [CI Build ID 📖](https://docs.currents.dev/guides/ci-build-id) before using `currents` in CI. It is **important** to set the `CI Build ID` explicitly if you are using sharding or multiple machines for the same test run. -3. Upload the test results to the Currents - - The `--project-id` and [--key](https://docs.currents.dev/guides/record-key) are used to identify the project and associate the results with the organization in the Currents dashboard. +> ℹī¸ The `CI Build ID` will be generated automatically if not set. ## Configuration @@ -38,10 +38,10 @@ Please note that all options apart from `--project-id` and `--key` are optional. | Property | Type | Description | Environment variable | Default | | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | --------------------------------------- | -| `-k, --key` | `string` | The record key to be used to record the results on the remote dashboard. Read more: https://currents.dev/readme/guides/record-key | `CURRENTS_RECORD_KEY` | - | -| `-p, --project-id` | `string` | The id of the project to record the test run. | `CURRENTS_PROJECT_ID` | - | +| `-k, --key` | `string` | The record key to record the results to Currents. Read more: https://currents.dev/readme/guides/record-key | `CURRENTS_RECORD_KEY` | - | +| `-p, --project-id` | `string` | The id of the project for reporting | `CURRENTS_PROJECT_ID` | - | | `--machine-id` | `string` | Unique identifier of the machine running the tests. If not provided, it will be generated automatically. See: https://currents.dev/readme/readme?q=machineId | `CURRENTS_MACHINE_ID` | `[random-string]` | -| `--report-dir` | `string` | The path from where the CLI command will read the Currents report | `CURRENTS_REPORT_DIR` | `.currents-report-[timestamp]-[uuidv4]` | +| `--report-dir` | `string` | The directory containng the test results created with one of the [supported](https://docs.currents.dev) reporters | `CURRENTS_REPORT_DIR` | `.currents-report-[timestamp]-[uuidv4]` | | `--ci-build-id` | `string` | The id of the build to record the test run. Read more: https://currents.dev/readme/guides/ci-build-id | `CURRENTS_CI_BUILD_ID` | `auto:[random-string]` | | `--debug` | `boolean` | Enable debug logs | `DEBUG="currents,currents:*"` | `falseu` | | `-t, --tag` | `string` | Comma-separated tag(s) for recorded runs in Currents | `CURRENTS_TAG` | - | @@ -50,10 +50,6 @@ Please note that all options apart from `--project-id` and `--key` are optional. The configuration is also available by running the CLI command with the `--help` argument. -**Note:** - -The `CI Build ID` and `Machine ID` will be generated automatically if not set. It is **important** to set the `CI Build ID` explicitly when the results from different machines are part of the same test run. Read more - [here](https://docs.currents.dev/guides/ci-build-id). - ## Troubleshooting Run the CLI command with the `--debug` argument or prefix it with `DEBUG="currents,currents:*"` to obtain detailed information about the command execution process.