# isHypothesisActive()

The primary method for running A/B tests with the Shoplift JavaScript API. Determines whether the current visitor is assigned to a specific hypothesis (variant). For manual API tests, the first call also triggers the visitor's test assignment.

### Signature

```typescript
window.shoplift.isHypothesisActive(hypothesisId: string): Promise<boolean>
```

### Parameters

| Parameter      | Type     | Required | Description                                                                                                       |
| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `hypothesisId` | `string` | Yes      | The unique identifier for your test variant. Found in the Shoplift dashboard when creating a JavaScript API test. |

### Returns

`Promise<boolean>` — resolves to:

| Value   | Meaning                                                                                                                                |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `true`  | Visitor is assigned to this specific hypothesis                                                                                        |
| `false` | Visitor is not assigned to this hypothesis (assigned to control, a different variant, test is inactive, visitor doesn't qualify, etc.) |

The promise may **reject** if an error occurs during visitor assignment (e.g., a network failure during splitting). See Error Handling for the recommended pattern.

### Basic Usage

```javascript
const isVariant = await window.shoplift.isHypothesisActive(
  'aa800953-3e22-4335-a53b-50f61db17538'
);

if (isVariant) {
  showVariantExperience();
} else {
  showControlExperience();
}
```

### Behavior by Trigger Type

The method's side effects depend on how you configured the test's trigger in the Shoplift dashboard.

#### Automatic Trigger

The visitor is assigned to a variant **during Shoplift's initialization**, before your code calls `isHypothesisActive()`. Calling the method simply reads the existing assignment.

```javascript
// Visitor is ALREADY assigned by the time this runs
if (window.shoplift) {
  const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
  // isActive reflects the assignment that happened during initialization
}
```

#### Manual Trigger

The visitor is assigned to a variant **on the first call** to `isHypothesisActive()`. Subsequent calls return the existing assignment.

```javascript
// No assignment yet — visitor is not in the test

button.addEventListener('click', async () => {
  // FIRST CALL: assigns the visitor and returns the result
  const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');

  // SUBSEQUENT CALLS: return the existing assignment (no re-assignment)
  const stillActive = await window.shoplift.isHypothesisActive('hypothesis-id');
  // isActive === stillActive (always)
});
```

This is useful when you only want to include visitors who perform a specific action (e.g., opening a cart or clicking a tab) in the test. See Test Triggers for a detailed comparison.

### Return Value Scenarios

#### Returns `true` when:

* The visitor is assigned to this specific hypothesis through normal random assignment
* The URL contains `?slVariant=<hypothesisId>` matching this hypothesis
* The URL contains `?slVariant=true` (forces all hypotheses to return true)

#### Returns `false` when:

* The visitor is assigned to control or a different variant
* The visitor is excluded from the test (`hypothesisId` is `null` in the assignment)
* The test is inactive or paused
* The visitor doesn't meet the test's targeting criteria
* The `hypothesisId` is invalid or not found

### Error Handling

The method returns a Promise that may reject if an error occurs during visitor assignment (for example, a network failure when splitting a visitor into a manual test). The method does **not** automatically fall back to `false` — your code is responsible for handling errors gracefully.

Always wrap calls in try/catch so visitors see a valid experience even if something goes wrong:

```javascript
try {
  const isVariant = await window.shoplift.isHypothesisActive('hypothesis-id');
  if (isVariant) {
    showVariantExperience();
  } else {
    showControlExperience();
  }
} catch (error) {
  console.error('Shoplift test check failed:', error);
  showControlExperience(); // Fall back to control on error
}
```

{% hint style="info" %}
Errors are only possible on the **first call** for a manual-trigger test, when the visitor is being assigned. Subsequent calls and all automatic-trigger calls read from local state and will not reject.
{% endhint %}

### Mutual Exclusion

API tests participate in Shoplift's mutual exclusion system. The behavior depends on the trigger type:

* **Automatic API tests** block all conditional tests (template, URL redirect, manual API) for that visitor. They have the same exclusion scope as theme and price tests.
* **Manual API tests** block global tests (theme, price, automatic API) for that visitor.

This means a visitor cannot be in both an automatic API test and a manual API test simultaneously.

### Assignment Persistence

After a visitor is assigned to a test, the assignment is stored in Shoplift's visitor state and **persists across page loads**. Subsequent calls to `isHypothesisActive()` for the same hypothesis read directly from local state without network requests.

### URL Parameter Overrides

For testing and QA, you can force specific outcomes using URL parameters:

| Parameter                   | Effect                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `?slVariant=<hypothesisId>` | Forces `true` for the matching hypothesis ID, `false` for all others                 |
| `?slVariant=true`           | Forces `true` for **all** hypotheses                                                 |
| `?isShopliftMerchant=true`  | Disables all Shoplift functionality (useful for debugging without test interference) |

```
https://yourstore.com/products/example?slVariant=aa800953-3e22-4335-a53b-50f61db17538
```