> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdecipher.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Execution

> Run custom JavaScript as a test step

## Overview

Code execution steps let you run custom JavaScript in the browser during a test. This is useful when your test needs to interact with APIs, set up data, or perform actions that aren't possible through the standard click/type/assert steps.

The code runs in the browser context via `page.evaluate()`, so you have access to `fetch()`, `document`, `window`, and other browser APIs.

## Adding During Recording (Recommended)

The easiest way to add a code step is during a Chrome extension recording. The code runs immediately so you can verify it works before saving.

<Steps>
  <Step title="Start a recording">
    Open the Decipher Recorder sidebar and click **Record Tab** to begin recording your user flow.
  </Step>

  <Step title="Click Add Code Step">
    In the recording sidebar, click the **+ Add Code Step** button. This appears between the action log and the "Watching..." indicator.
  </Step>

  <Step title="Write your code">
    Enter your JavaScript in the code editor. You can use top-level `await` — the code is wrapped in an async function automatically. A template with a `fetch` example is pre-filled to get you started. Use `return` to pass a value back — it will be shown in the step results.
  </Step>

  <Step title="Add a description">
    Describe what the code does (e.g., "Create test user via API"). This description appears in the action log and in the generated test steps.
  </Step>

  <Step title="Run & Add Step">
    Click **Run & Add Step**. The code executes immediately in the page. You'll see whether it succeeded or failed, along with any return value. The step is added to your recording's action log with before/after screenshots.
  </Step>

  <Step title="Continue recording">
    Keep recording the rest of your flow. When you generate a test, the code step is included at the correct position in the test.
  </Step>
</Steps>

<Tip>
  If a code step fails, the error is shown but your recording continues. Delete the step and try again with corrected code.
</Tip>

## Adding in Edit Mode

You can also add code steps to an existing test:

<Steps>
  <Step title="Open Edit Mode">
    Navigate to your test and click **Edit Mode**.
  </Step>

  <Step title="Add a Code Execution step">
    Click **Add code execution** between any two steps.
  </Step>

  <Step title="Write your code and save">
    Enter your JavaScript, set a description and timeout, then click **Save**.
  </Step>
</Steps>

## Example

```javascript theme={null}
const response = await fetch(
  'https://jsonplaceholder.typicode.com/posts',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: 'Test Post', body: 'Hello', userId: 1 }),
  }
);

const data = await response.json();

// Return a value to see it in the step results
return data.id;
```

The last expression returned by your code is captured and displayed in the step results, so you can verify the step did what you expected.

## Timeout

Each code step has a configurable timeout (default: 30 seconds, max: 300 seconds). If the code doesn't finish within the timeout, the step fails. You can adjust the timeout when adding the step.

## Behavior

* **Errors** — If the code throws an error or times out, the step fails and the error message is shown in the test results.
* **Return values** — If your code returns a value, it is captured and displayed in the step results.
* **Variable persistence** — Variables declared with `const`/`let` don't persist across steps. Use `window.myVar = ...` to share data between code steps.
* **Navigation** — If your code navigates the page (e.g., `window.location.href = ...`), subsequent steps run on the new page.

<Note>
  Code execution steps are user-authored only — they cannot be generated by AI-based editing.
</Note>

***

*Need help? [Contact our support team](mailto:team@getdecipher.com).*