# 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](https://learning.contextqa.com/web-testing/test-steps-editor) 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](https://learning.contextqa.com/web-testing/test-steps-editor)
* [Test Data Management](https://learning.contextqa.com/web-testing/test-data-management)
* [Creating Test Cases](https://learning.contextqa.com/web-testing/creating-test-cases)

{% 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 %}