# Migrating and upgrading

> Move a Cucumber setup from probara import cucumber, or from Qase's cucumber-js reporter, to @probara/cucumber-reporter, and upgrade the reporter.

## From `probara import cucumber`

If you already send the Cucumber JSON report with `probara import cucumber`, the reporter finds the same
cases. It builds the same keys as the sync and the import, so switching keeps each scenario on its case
and its history.

Switching takes three steps:

1. Install the reporter next to cucumber-js: `npm install --save-dev @probara/cucumber-reporter`.
2. Add it to `format` in `cucumber.js`, with your Project ID in `formatOptions.probara`, as the
   [quick start](https://docs.probara.net/en/developers/ci-integrations/cucumber/) shows.
3. Remove the `cucumber-js --format json:...` step and the `probara import cucumber` step from your
   pipeline. Keep the sync step.

Remove the import step once the reporter runs. An import after a run that the reporter already reported
creates a second run with the same results.

What changes:

- The results are sent at the end of the run, from the same command, not in a later step.
- The files a scenario attaches with `this.attach`, `this.log` and `this.link` are uploaded. The import
  sends no attachments.

Keep `probara import cucumber` for the reports of Cucumber-JVM, playwright-bdd and other tools that write
Cucumber JSON. The reporter is for cucumber-js. The [CLI page](https://docs.probara.net/en/developers/cli/#import-cucumber-results)
describes that command.

## From Qase's cucumber-js reporter

[`qase-cucumberjs`](https://github.com/qase-tms/qase-javascript/tree/main/qase-cucumberjs) links a
scenario to a Qase case with a tag, and sends its results to Qase. This reporter does the same for
Probara, with two differences: the scenarios come from Git through `probara sync gherkin`, and the link
is the `@probara:<ID>` tag.

| What              | Qase                                             | Probara                                                              |
| ----------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
| Package           | `qase-cucumberjs`                                | `@probara/cucumber-reporter`, with `@cucumber/cucumber`              |
| Link a scenario   | `@QaseID=12`                                     | `@probara:SHOP-12` (the case's display ID)                           |
| Token and project | `QASE_TESTOPS_API_TOKEN`, `QASE_TESTOPS_PROJECT` | `PROBARA_API_TOKEN`, `PROBARA_PROJECT`                               |
| Cases             | Created by the reports                           | Synced from the feature files, then linked by key                    |
| Attachments       | Sent by the reporter                             | Sent by the reporter, with `this.attach`, `this.log` and `this.link` |

1. Remove `qase-cucumberjs` and its entry from `cucumber.js`.
2. Install the reporter: `npm install --save-dev @probara/cucumber-reporter`.
3. Add it to `format` and set `projectId` in `formatOptions.probara`, as the
   [quick start](https://docs.probara.net/en/developers/ci-integrations/cucumber/) shows.
4. Replace each `@QaseID=<n>` tag with `@probara:<ID>`, using the case's display ID in Probara. The tag
   is not a tag of the case: it only links the scenario.
5. Sync the feature files on the default branch: `npx @probara/cli sync gherkin "features/**/*.feature"`.
   A scenario then lands on its case by its key, even before it has a tag.

## Upgrading the reporter

Before 1.0, a minor version may bring breaking changes. Pin the version of `@probara/cucumber-reporter`
in your lockfile, and read the
[changelog](https://github.com/cynch-me/probara-sdk/blob/main/packages/cucumber-reporter/CHANGELOG.md)
before you upgrade.