# Simulation

Simulation runs a single file in an isolated sandbox against a realistic sample event, captures the result, and shows you exactly what EdgeTag would do with the event — without anything reaching production.

<figure><img src="/files/bJc8iMDWR6hYe5ZLTytz" alt=""><figcaption></figcaption></figure>

### What gets run

When you click **Simulate**, Playground:

1. Takes the code from the file you selected.
2. Injects your [Secrets](/playground/transformation/secrets.md) into `params.variables` (scoped to edge vs. browser — see Secrets).
3. Runs the file against the current sample event.
4. Captures logs, the return object, and any thrown error.

Because Transformations don't make HTTP requests, the captured output is mostly about the **return object** — the thing that tells EdgeTag how to change the event.

### Sample events

Every session starts with three pre-populated sample events you can switch between:

* **Purchase** — a full purchase with two line items, user PII, and realistic `providerData` (an `fbclid`, a `gclid`, UTM parameters).
* **PageView** — a page view with a name and category.
* **AddToCart** — a single-item add-to-cart.

The sample also includes a `platform` (`SHOPIFY`), `userCustomData`, and `hostData` (`userAgent`, `ip`, `country`, and so on).

### What you see

The simulation output has three sections:

* **Return** — the object your function returned: `{ payload?, user?, additionalEvents?, skipEvent? }`. This is the most important part of the output for a Transformation.
* **Logs** — everything you wrote with `params.logger.log(...)` or `params.logger.error(...)`.
* **Error** — if your code threw, the error message and stack.

Sensitive values are redacted automatically: any header or body key matching `authorization`, `token`, `api-key`, `api_key`, `secret`, `password`, or `cookie` is replaced with `[REDACTED]` before being shown.

### Reading the result

Three quick patterns for reading simulation output:

**Confirm you dropped an event.** The return should be exactly `{ "skipEvent": true }`:

{% code title="Simulation output" %}

```json
{
  "result": { "skipEvent": true },
  "logs": []
}
```

{% endcode %}

**Confirm your payload enrichment.** Compare `result.payload.data` against the input to see the fields you added:

{% code title="Simulation output" %}

```json
{
  "result": {
    "payload": {
      "eventName": "Purchase",
      "data": {
        "orderId": "ORD-2024-001234",
        "value": 149.99,
        "currency": "USD",
        "source": "website",
        "valueUSD": 149.99
      }
    }
  }
}
```

{% endcode %}

**Confirm your fan-out.** `additionalEvents` should contain the extra events you emitted:

{% code title="Simulation output" %}

```json
{
  "result": {
    "additionalEvents": [
      {
        "eventName": "Purchase_Facebook",
        "eventId": "evt_123abc456def",
        "data": { "orderId": "ORD-2024-001234", "value": 149.99 }
      }
    ]
  }
}
```

{% endcode %}

### Simulating each level independently

Each level is simulated independently. `tagRoot` runs once; `tagChannel` and `tagInstance` are invoked per provider and need `params.providerId` to be set. The result you see is specifically the return of the level you selected — to test a `tagChannel` rule that only fires for Facebook, select the `tagChannel` file and make sure the sample includes `providerId: 'facebook'`.

{% hint style="info" %}
Simulate after every meaningful change. Because Transformations are pure event transforms, the return object is a complete description of what your rule does — if the return looks right, the rule is right.
{% 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://docs.edgetag.io/playground/transformation/simulation.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.