Parallel Execution Best Practices

To accelerate CI feedback loops, Gherkio supports multi-threaded, parallel test executions. However, running integration tests concurrently requires careful state separation.

⚡ Running Parallel Tests from the CLI

Run a directory of tests with custom concurrency levels using the --parallel (or -p) flag:

# Run tests with 4 parallel execution threads
gherkio run .gherkio/tests/ -p 4
```text

`--parallel 4` means up to four **different test files** run at once. It is intended to speed up
a directory or suite run; it is not a virtual-user load model.

To repeat the **same workflow** with concurrent virtual users, use:

```bash
gherkio run .gherkio/tests/checkout.yaml \
  --virtual-users 2 \
  --iterations-per-user 3 \
  --report html
```text

Here, two users run concurrently and each user performs three sequential iterations, for six
workflow executions in total. Each user's variables are isolated from the other user. The HTML
report preserves the VU/iteration hierarchy and lets you expand or collapse each workflow.

---

## ⚠️ The Concurrent Mutation Problem

If multiple tests manipulate the exact same shared DB entity, race conditions will occur:

```mermaid
sequenceDiagram
    participant T1 as Test 1 (Edit Laptop Price)
    participant DB as Shared Database
    participant T2 as Test 2 (Assert Laptop Details)

    T1->>DB: UPDATE laptop WHERE id = 1 SET price = 10.00
    T2->>DB: GET laptop WHERE id = 1
    Note over T2: Asserts price == 12.00 (expected original)
    DB-->>T2: returns price = 10.00
    Note over T2: ❌ Test Failed!
```text

---

## 🛡️ Key Safety Strategies

### 1. Isolated Dynamic Data
Avoid hardcoding entity identifiers or emails. Utilize Gherkio's dynamic generators to create unique resources per test thread:

```yaml
steps:
  - request:
      method: POST
      url: /v1/users
      body:
        email: $randomEmail         # Unique email per thread!
        name: "Test User"
```text

### 2. Microservice Routing Isolation
If your microservices support multi-tenant isolation, inject tenancy headers:

```yaml
steps:
  - request:
      method: GET
      url: /v1/products
      headers:
        X-Tenant-ID: "tenant-${uuid}"  # Dynamic tenant separation
```text