# evaluate

The `evaluate` step.

Runs your own JavaScript in the page. The healer cannot see inside it, so lint warns `W006`, and it requires a paid organisation.

Type: `object`

## Keys

| Key | Type | Description |
|---|---|---|
| `evaluate.args` | `object` | A JSON object passed to the script as its arguments. |
| `evaluate.into` | `string` | The variable that receives the script's return value, written `vars.<name>`. |
| `evaluate.max_result_bytes` | `integer` | The largest return value accepted, in bytes. Required, at most `1048576` (lint `E003`). |
| `evaluate.script` | `string` | The JavaScript function body to run, such as `return document.title`, at most 16 KB (lint `E003`). |
| `evaluate.timeout_ms` | `integer` | How long the script may run, in milliseconds. Required, at most `5000` (lint `E003`). |

Every step also takes the [common step keys](https://docs.kaab.ist/reference/dsl/steps#common-keys): `expect`, `id`, `if`, `name`, `on_error`, `optional`, `retry`, `side_effect`, `timeout_ms`, `x_kaab`.

## Example

```json
{
  "evaluate": {
    "script": "return window.__STATE__.total",
    "into": "vars.total",
    "timeout_ms": 5000,
    "max_result_bytes": 1048576
  }
}
```

From the contract fixture `evaluate-opaque`, a program the test suite validates.