@currents/cmd 2.1.0 → 2.3.0

package/README.md

@@ -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.
 
@@ -163,6 +180,10 @@ npx currents skill --install --dir .claude/skills
 
 The skill is also in this repository, in `skills/currents-cli`: `npx skills add https://github.com/currents-dev/currents-reporter --skill currents-cli`.
 
+## Guides
+
+`npx currents docs` lists the guides that ship with the package, such as the CI setup steps. `npx currents docs <topic>` prints one as Markdown. The guides are in [docs/](./docs).
+
 ## 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. Keys are hidden in the debug output.