# Steps and attachments

> Which parts of a Cucumber step are sent, how Background steps and hooks show, and which files a scenario attaches with this.attach, this.log and this.link.

Each step a scenario runs is one step of its result, in the order the feature file gives them.

## Steps

| Step field   | What it holds                                                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `keyword`    | `Given`, `When`, `Then`, `And`, `But` or `*`, as written. A step written in another language has none.                        |
| `action`     | The step text. In an outline row, the values of that row are filled in.                                                       |
| `status`     | [Its status](https://docs.probara.net/en/developers/ci-integrations/cucumber/results-and-retries/#step-statuses), from Cucumber's result of the step. |
| `durationMs` | The step's duration, in milliseconds.                                                                                         |
| `error`      | The message of a failed step: Cucumber's error text. An ambiguous step with no message says why.                              |
| `data`       | A Doc String's content, or a Data Table as lines of pipes, such as `\| item \| price \|`.                                     |

```gherkin
When the customer sends the receipt:
  """
  Thank you for the order.
  """
Then the receipt table is:
  | item | price |
  | book | 12    |
```

The first step's `data` is `Thank you for the order.`. The second step's `data` is its table, as lines of
pipes: `| item | price |` and then `| book | 12 |`.

## Background

The Background steps of a scenario sit under one `Background` step, with their own steps nested in it.
Its status is the rollup of its steps, and its duration is their sum. A Background of a Rule applies to
the scenarios under the Rule, and sits in the same way.

## Hooks

Hooks (`Before` and `After`) are not steps, so they are not sent. A hook that fails fails its scenario,
and its message is the scenario's error, or `The hook failed` when it has none. Its duration counts in
the scenario's duration.

## Steps that did not pass

- A step that failed, or is ambiguous (more than one definition matches it), fails its scenario.
- An undefined or pending step did not run. It is `skipped`, and so is its scenario, unless a step failed.
- The steps after a failed step did not run, so they are `skipped`.

[Results and retries](https://docs.probara.net/en/developers/ci-integrations/cucumber/results-and-retries/#scenario-statuses)
gives the rules in full.

## Attachments

Files a scenario attaches with the World are uploaded to its result, as the other reporters upload theirs:

| Call in a step or hook                       | Uploaded as                                                                     |
| -------------------------------------------- | ------------------------------------------------------------------------------- |
| `this.attach(text, 'text/plain')`            | A text file named `attachment.txt`                                              |
| `this.attach(buffer, 'image/png')`           | An image named `attachment.png`                                                 |
| `this.attach(data, { mediaType, fileName })` | A file named `fileName`, with an extension from its media type when it has none |
| `this.log('a line')`                         | A text file named `log.txt`, one per call                                       |
| `this.link(url)`                             | A text file named `link.txt`, holding the link                                  |

```js
When('the page is shown', async function () {
  this.attach(await page.screenshot(), { mediaType: 'image/png', fileName: 'page.png' });
  this.log('the cart had one book');
});
```

- A file attached in a step belongs to that step, and shows with it. A file attached in a `Before` or
  `After` hook belongs to the result.
- `uploadAttachments: false` (`PROBARA_UPLOAD_ATTACHMENTS=false`) uploads no file.
- The limits of every reporter apply. A result sends at most 20 files, and images that Probara refuses
  (PNG, JPEG or WebP over 10 MiB, or over 8192 pixels on a side) are skipped with a warning. See
  [attachments in `@probara/core`](https://github.com/cynch-me/probara-sdk/blob/main/packages/core/README.md#attachments).
- A file that cannot be uploaded does not fail the run: the summary counts it as skipped or failed.
- [`probara import cucumber`](https://docs.probara.net/en/developers/cli/#import-cucumber-results) sends no attachments from a
  report. Use the reporter to send the files a scenario attaches.