# Export a session as a test

`export` writes a spec from the recorded steps. Refs are replaced with stable selectors. For a web page, the first of these that matches exactly one element is used: a test id (`data-testid`, `data-test`, `data-qa`), a [role selector](/docs/selectors.md#role-selector) such as `role/button[name="Add to cart"]`, an accessible name (`aria/Add to cart`), an id, the text of a button or link, a form field name, and finally a CSS path.

A role selector or accessible name is skipped when the name the snapshot computed may not be the one the driver computes, for example a name next to an icon, with a non-breaking space or spread over block elements. This happens in WebDriver BiDi and in classic sessions, and the text or CSS path is used instead. When the element has no selector at all, such as one of several nameless buttons inside shadow roots, the action still runs on the ref. The step is recorded as `ref('e12')` with a comment: it replays in the session, but `export` stops with `Step N still contains ref()` until the step is removed or rewritten with a selector.

```
npx wdio session export --out test/specs/cart.e2e.ts

npx wdio run wdio.conf.ts --spec test/specs/cart.e2e.ts
```

`history` prints the steps before you export. `history clear` drops them.

## Page objects[​](#page-objects "Direct link to Page objects")

`--page-objects` writes a page object next to the spec. Selectors are grouped by the path they ran on. A literal `$('…')` in a recorded step becomes a getter. `$$`, strings that happen to contain `$('…')`, and a dynamic `$(selector)` stay as they are.

```
npx wdio session export --page-objects --out test/specs/cart.e2e.ts
```

The command refuses to overwrite a page object that is already in the output directory. Move `--out` or remove that file first. The spec file itself is written again.

A `import` at the top of an `exec` step is hoisted to the top of the spec, outside the test function.

## Helpers[​](#helpers "Direct link to Helpers")

Add a file under `.wdio/helpers/` when a step is too long for `exec`. Each file default-exports a function that receives the browser and registers commands with `addCommand`. Relative imports stay relative to that file. Bare package imports resolve from the project.

.wdio/helpers/login.js

```
import { mark } from './util.js'



export default function login (browser) {

    browser.addCommand('fillLogin', async (email) => {

        await browser.$('#email').setValue(email + mark)

    })

}
```

Helpers are loaded when the session opens and again with `npx wdio session helpers --reload`. If `.wdio/helpers` does not exist yet, the session watches for it. Helpers become custom commands in the exported test.

## Next steps[​](#next-steps "Direct link to Next steps")

* [Run code](/docs/session/exec.md) — the steps `export` records
* [Commands](/docs/session-commands.md) — `export`, `history` and `helpers` flags
