# Custom Code Steps

{% hint style="info" %}
**Who is this for?** SDETs and developers who need to execute custom JavaScript within a test case for logic that cannot be expressed as a natural language step.
{% endhint %}

Custom code steps let you write JavaScript that executes during test runtime. Use them for complex calculations, custom data transformations, direct DOM manipulation, or any scenario where a natural language instruction is insufficient.

## Prerequisites

* You have created or opened a test case.
* You are familiar with the [Test Steps Editor](/web-testing/test-steps-editor.md) basics.
* You have working knowledge of JavaScript.

***

## Adding a custom code step

1. Open a test case and click **Add Step**.
2. In the step builder sidebar, select **Custom Code**.
3. Select **JavaScript** from the **Language** dropdown.
4. Write your code in the code editor.
5. Click **Create Step** to add the step to your test case.

***

## Fields

| Field           | Description                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------- |
| **Language**    | The scripting language. Currently supports **JavaScript**.                                    |
| **Code**        | The JavaScript code to execute at runtime.                                                    |
| **Description** | A plain-English summary of what the code does. Appears in the step list and execution report. |

***

## Example: Generate a unique identifier

```javascript
// Generate a unique email for registration testing
const timestamp = Date.now();
const uniqueEmail = `testuser_${timestamp}@example.com`;
return uniqueEmail;
```

***

## Example: Calculate and verify a total

```javascript
// Calculate expected cart total from individual prices
const prices = [19.99, 24.50, 7.99];
const expectedTotal = prices.reduce((sum, price) => sum + price, 0).toFixed(2);
return expectedTotal;
// => "52.48"
```

***

## Example: Parse and transform data

```javascript
// Extract order IDs from a JSON response stored in a variable
const response = JSON.parse(context.variables.orderListResponse);
const orderIds = response.body.orders.map(order => order.id);
return orderIds.join(', ');
```

***

## Advanced settings

| Setting              | Description                                                             |
| -------------------- | ----------------------------------------------------------------------- |
| **Skip Step**        | Skip this step during execution without removing it from the test case. |
| **Mark as Optional** | If enabled, a failure on this step does not fail the overall test case. |

***

## Tips & best practices

* **Add a descriptive Description field** so the step is understandable in the execution report without reading the code.
* **Keep code minimal.** Custom code steps are for logic that natural language steps cannot handle. If a task can be described in plain English, use an AI Agent step instead.
* **Use custom code for data transformation** between steps — formatting dates, calculating expected values, parsing complex response structures.
* **Avoid long-running operations.** The step has a default timeout of 30 seconds. If your code needs more time, increase the step timeout.

## Troubleshooting

**Custom code step fails with a syntax error** Check the browser console output in the execution report. JavaScript syntax errors surface as step failures with the error message in the step details. Validate your code in a browser console before pasting it into the step editor.

**Variables from previous steps are not accessible** Verify the variable name is spelled correctly and that the step that sets the variable runs before the custom code step. Variable names are case-sensitive.

## Related pages

* [Test Steps Editor](/web-testing/test-steps-editor.md)
* [Test Data Management](/web-testing/test-data-management.md)
* [Creating Test Cases](/web-testing/creating-test-cases.md)

{% hint style="info" %}
**70% less manual test maintenance with AI self-healing.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See ContextQA create and maintain tests for your web application.
{% endhint %}


---

# 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://learning.contextqa.com/web-testing/custom-code-steps.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.