@currents/cmd 2.2.0 → 3.0.0

package/README.md

@@ -4,7 +4,7 @@ CLI tool for [Currents](https://currents.dev) - a cloud platform for debugging,
 
 ## Installation
 
-Requires Node.js 20 or later.
+Requires Node.js 22.13 or later.
 
 ```sh
 npm install @currents/cmd --save-dev
@@ -29,7 +29,7 @@ For JUnit XML reports, `run upload` converts them to the Currents format first,
 npx currents run upload --project-id=xxx --key=yyy --input-format junit --input-file "reports/*.xml" --framework postman
 ```
 
-`--framework` takes `postman`, `node`, `vitest` or `wdio`. The converted reports are saved to `--output-dir`, or `--report-dir`, or a new folder in `.currents`. A folder you name must be empty or not exist yet.
+`--framework` takes `cypress`, `postman`, `node`, `vitest` or `wdio`. For Cypress run results saved by `after:run`, use `--input-format cypress-json --input-file results.json` without `--framework`: it uploads every attempt, screenshot and video. The converted reports are saved to `--output-dir`, or `--report-dir`, or a new folder in `.currents`. A folder you name must be empty or not exist yet.
 
 ℹ️ 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 using `--ci-build-id` option, if you are using CI sharding or multiple CI machines to parallelize your tests. If not set explicitly, the `CI Build ID` will be set to a random value.
 
@@ -46,6 +46,21 @@ Obtain `--project-id` and [--key](https://docs.currents.dev/guides/record-key) f
 
 For [Detox](https://wix.github.io/Detox/) runs reported by `@currents/jest`, `currents run upload` also attaches the videos, screenshots and logs that Detox recorded to the matching test attempt, adds the element actions of `detox.trace.json` as steps, and uploads `detox.trace.json`. Run it after `detox test` exits: Detox finishes writing the files only then.
 
+`currents run upload` applies the [actions](https://docs.currents.dev/guides/currents-actions) of the project to the results before it sends them. The tests already ran, so each attempt keeps its result, errors and artifacts:
+
+- a skip action marks the test as skipped
+- a quarantine action marks a failed test as skipped
+- a tag action adds its tags to the test
+
+The dashboard shows which action changed each test. Actions with regex or date conditions are not applied yet. The command uploads the results without actions when it can't get them.
+
+With `--fail-on-failures`, or `CURRENTS_FAIL_ON_FAILURES=true`, the command exits with 1 after it uploads the results when a test failed, and lists the failed tests. A test that an action quarantined or skipped does not count. Let the test command pass and use the upload to fail the CI job, so a quarantined test does not fail it:
+
+```sh
+npx detox test || true
+npx currents run upload --fail-on-failures
+```
+
 ### Configuration
 
 Please note that all options apart from `--project-id` and `--key` are optional.
@@ -59,8 +74,10 @@ Please note that all options apart from `--project-id` and `--key` are optional.
 | `--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                                                                                                                                            | `CURRENTS_DEBUG`              | `false`                |
 | `-t, --tag`            | `string`  | Comma-separated tag(s) for recorded runs in Currents                                                                                                         | `CURRENTS_TAG`                | -                      |
+| `--environment`        | `string`  | The environment to label the run with, e.g. `staging`                                                                                                        | `CURRENTS_ENVIRONMENT`        | -                      |
 | `--disable-title-tags` | `boolean` | Disable extracting tags from test title, e.g. `Test name @smoke` would not be tagged with `smoke`                                                            | `CURRENTS_DISABLE_TITLE_TAGS` | `false`                |
 | `--remove-title-tags`  | `boolean` | Remove tags from test names in Currents, e.g. `Test name @smoke` becomes `Test name` in the dashboard                                                        | `CURRENTS_REMOVE_TITLE_TAGS`  | `false`                |
+| `--fail-on-failures`   | `boolean` | Exit with 1 after uploading when a test failed. A test quarantined or skipped by a Currents action does not count                                            | `CURRENTS_FAIL_ON_FAILURES`   | `false`                |
 
 An option on the command line wins over its environment variable. The configuration is also available by running the CLI command with the `--help` argument.
 
@@ -75,6 +92,17 @@ npx currents run attach --key <record-key> --project-id <id> --ci-build-id <buil
 
 Without `--spec`, the files are attached to the whole run. For the options, run `npx currents run attach --help`.
 
+## Share a run
+
+`currents run share` prints a public link to a run, or to one spec file or test of it, and a link to the same content as Markdown. It uses an API key with write access:
+
+```sh
+npx currents run share <run-id>
+npx currents run share <run-id> --instance-id <instance-id> --test-id <test-id> --purpose fix
+```
+
+`--purpose report`, the default, holds every test with its attempts and files, for a person. `--purpose fix` holds the failure context, for an agent fixing the tests. For the options, run `npx currents run share --help`.
+
 ## Cancel a run
 
 `currents run cancel` cancels a run in progress, for example when its CI job is cancelled. It uses the record key: