# Test Triggers

When creating JavaScript API tests, you'll need to choose between Automatic and Manual triggers. This determines when and how visitors become eligible to participate in your test.

#### Automatic Trigger

With automatic triggers, visitors enter the test immediately when the page loads, before any JavaScript API calls.

**How it works:**

```javascript
// Visitor is ALREADY in the test before this code runs
const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
// This just checks their assignment
```

**Characteristics:**

* Test participation triggered on page load
* Every visitor who meets targeting criteria enters the test
* Test participation tracked even if feature isn't used
* Best for always-visible elements

**Use Cases:**

* Hero banners
* Navigation changes
* Global UI elements
* Chat widgets
* Promotional bars
* Footer modifications

**Example: Automatic Trigger for Hero Banner**

```javascript
// Test triggers for ALL visitors immediately on page load
document.addEventListener('DOMContentLoaded', async () => {
  const showNewHero = await window.shoplift.isHypothesisActive('hero-v2-id');
  
  if (showNewHero) {
    document.querySelector('.hero').innerHTML = newHeroContent;
  }
  // Even visitors who scroll past immediately are in the test
});
```

#### Manual Trigger

With manual triggers, visitors only enter the test when your code calls isHypothesisActive() for the first time.

How it works:

```javascript
// No test participation yet
button.addEventListener('click', async () => {
  // Test participation triggered NOW, on first call
  const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
  // Visitor is now permanently assigned to a variant
});
```

Characteristics:

* Test participation triggered by JavaScript call
* Only visitors who trigger the action enter the test
* More accurate test results (only engaged users)
* Reduces test pollution from unengaged visitors

Use Cases:

* Mini carts
* Quick view modals
* Dropdown menus
* Search overlays
* Product quick-add features
* Any user-triggered interaction

Example: Manual Trigger for Mini Cart

```javascript
// Test only triggers when visitors actually open the cart
document.querySelector('.cart-icon').addEventListener('click', async () => {
  // First click triggers test participation
  const useNewCart = await window.shoplift.isHypothesisActive('cart-v2-id');
  
  if (useNewCart) {
    openNewMiniCart();
  } else {
    openStandardCart();
  }
  // Only cart users are in the test data
});
```

#### Choosing the Right Test Trigger

**Decision Framework**

* **Is the tested element always visible?**
  * Yes → Automatic trigger
  * No → Manual trigger
* **Should all visitors be in the test?**
  * Yes → Automatic trigger
  * No → Manual trigger
* **Is it activated by user action?**
  * Yes → Manual trigger
  * No → Automatic trigger
* **Do you want to measure engagement rate?**
  * Yes → Manual trigger
  * No → Either works

| Aspect                   | Automatic Trigger        | Manual Trigger               |
| ------------------------ | ------------------------ | ---------------------------- |
| When test triggers       | Page load                | First API call               |
| Visitors in test         | All who meet targeting   | Only those who interact      |
| Best for                 | Always-visible elements  | User-activated features      |
| Sample size              | Larger (all visitors)    | Smaller (engaged users only) |
| Statistical significance | Reached faster           | Takes longer                 |
| Data quality             | Includes unengaged users | Only engaged users           |
| Performance impact       | Immediate assignment     | Deferred assignment          |