# currents convert

`currents convert` allows converting test reports created by various frameworks to a format compatible with Currents API. A typical workflow is:

* Run tests using your preferred framework and save the results in a file
* Convert the report using `currents convert` command
* Upload the report to Currents using [currents upload](/resources/reporters/currents-cmd/currents-upload.md) command

### Supported formats

The command converts files of one of the supported format, generated by the one of the supported frameworks.

Support frameworks

| Framework      | Supported                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------- |
| Postman        | ✅                                                                                           |
| Vitest         | ✅                                                                                           |
| WebdriverIO    | ✅                                                                                           |
| NodeJS Testing | ✅ (see [@currents/node-test-reporter](/resources/reporters/currents-node-test-reporter.md)) |
| Cypress        | 👷🏾‍♀️ work in progress                                                                    |

If you're interested in enabling support for more frameworks, please get in touch with our support team.

### Usage

```bash
npx currents convert \
  --input-format=<format> \
  --input-file=<pattern> \
  --output-dir=<path> \
  --framework=<string> \
  --framework-version=<string>
```

Example:

```bash
npx currents convert \
  --input-format=junit \
  --input-file=./tests.xml \ 
  --output-dir=.currents/report-01 \ 
  --framework=postman \
  --framework-version=v11.20
# Reading the configuration
[currents] Convertion files: tests.xml
# Creating the config.json file...
# Converting files to internal Currents format
[currents] Conversion completed, report saved to: .currents/report-01
```

### Configuration

`currents convert` options apart from `--framework-version` are required. Use `--help` flag to list the available options.

* `--input-format`
  * The format of the input test reports. Use the `--help` flag to see the supported formats
  * **Type:** `junit`
* `--input-file`
  * Comma-separated glob patterns to match the test results files (e.g., "report1.xml,report2.xml)
  * The multi-file match is only available starting on version 1.6.8 of `@currents/cmd` package.
  * **Type:** `string`
* `-o, --output-dir`
  * The directory to save the converted test reports
  * **Type:** `string`
* `--framework`
  * The testing framework used to generate the test reports
  * **Type:** `postman, vitest, wdio`
* `--framework-version`
  * The version of the testing framework used to generate the test reports
  * **Type:** `string`
* `--debug`
  * Enable debug logs
  * Environment variable: `DEBUG=currents*`
  * **Type:** `boolean`

### Artifacts

Artifacts are files that can be linked with specific `instance`, `test` or `attempt` according to the [#artifact-level](#artifact-level "mention") of the artifact.&#x20;

The artifacts are taken from the JUnit XML file that can be read from this tags structure:

```
<properties>
      <property name="currents.artifact.{level}.path" value="./artifacts/manual/coverage.json" />
      <property name="currents.artifact.{level}.type" value="coverage" />
      <property name="currents.artifact.{level}.contentType" value="application/json" />
      <property name="currents.artifact.{level}.name" value="Test Coverage" />
</properties>
```

if the artifact is at attempt level it must also include the attempt index:

```
<properties>
      <property name="currents.artifact.attempt.{n}.path" value="./artifacts/video.mp4" />
      <property name="currents.artifact.attempt.{n}.type" value="video" />
      <property name="currents.artifact.attempt.{n}.contentType" value="video/mp4" />
      <property name="currents.artifact.attempt.{n}.name" value="Test Video" />
</properties>
```

* For `instance` level artifacts, the `<properties>` tag must exist within a `<testsuite>` tag.
* For `test` and `attempt` level artifacts, the `<properties>` tag must exist within a `<testcase>` tag.

See [Data Format Reference](/resources/reporters/data-format-reference.md#artifact) for a more specific data structure and the [JUnit example in the repository](https://github.com/currents-dev/currents-reporter/blob/main/examples/junit/junit-attempts.xml).

#### Level <a href="#artifact-level" id="artifact-level"></a>

The generic API reports support three types [#artifact-type](#artifact-type "mention") of artifact levels:

* `attempt`: Corresponds to the attempts (retries) made on each test.
* `test`: Is the specific test code executed for a testing framework.
* `instance`: Group of tests in a spec file.

#### Type <a href="#artifact-type" id="artifact-type"></a>

Currents Generic API accepts the following types of artifacts, each one according to the artifact level.

* `attempt`: `video`, `screenshot`, `attachment`
* `test`: `attachment`
* `instance`: `coverage`, `attachment`, `stdout`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.currents.dev/resources/reporters/currents-cmd/currents-convert.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.