Title: Headline Testing troubleshooting
Author: Lucas Radke
Published: June 16, 2025
Last modified: November 12, 2025

---

 1. [Troubleshooting common issues](https://docs.parse.ly/troubleshooting-issues/)
 2. Headline Testing troubleshooting

#  Headline Testing troubleshooting

## Valid vs. invalid HTML structure

To ensure accurate testing and tracking, Parse.ly’s Headline Testing requires a 
specific HTML structure. The system identifies the control headline using an anchor(`
<a>`) tag that must follow a strict format.

### Requirements for a valid HTML structure

 * The control headline must be included **within the anchor tag’s content**.
 * The anchor tag may contain multiple child elements, but **at least one child 
   must contain only the control headline text**.
 * The control headline **must not appear outside the anchor**.

### Valid example

    ```lang-php
    <a href="/example-article">
      <h2>This is the control headline</h2>
    </a>
    ```

In this case, the anchor tag contains one child element, and that element holds 
only the control headline. This structure is valid and supported.

### Invalid examples

#### Example 1: Additional text

    ```lang-php
    <a href="/example-article">
      <h2>Read more: This is the control headline</h2>
    </a>
    ```

This is invalid because the tag containing the control headline contains additional
text. The system cannot reliably extract the control headline.

#### Example 2: Headline outside the anchor

    ```lang-php
    <div class="caption">
      <div class="category">Tips</div>
      <h2 class="title">How to Optimize Headlines with Testing</h2>
    </div>
    <a href="/article/headline-testing-101" title="How to Optimize Headlines with Testing"></a>
    ```

This is invalid because the control headline is placed outside the anchor. Although
the anchor includes a title attribute, this is not sufficient for headline testing.
The system requires the actual headline text to appear inside the anchor’s content.

## Headlines are not being replaced

| **Possible issue: **The control headline is being selected as the variant.
**Solution:** Check if the anchor has the `vipexp-swapped-element` class. If it does, the system is working as expected. | 
| **Possible issue:** The script is being executed after the first contentful paint.**Solution:** Try loading the script synchronously or enabling flicker control. | 
| **Possible issue:** Mismatch in the URL or control text.**Solution:** Ensure the anchor’s `href` attribute includes the canonical URL path. Additionally, the anchor must contain either:1. The **exact** headline text with no extra text (though it may have child elements), or2. At least one child element that **exclusively** contains the exact headline text. |

## Unable to see the ‘Create Test,’ ‘Start Test,’ or ‘End Test’ buttons

**Possible issue:** You do not have the [necessary permissions](https://docs.parse.ly/dashboard/headline-testing-tab/access-permissions/)
to create or end tests.

**Solution:** By default, admins have the permission to manage headline tests. If
you are not an admin, you can request the Manage Headline Test permission from an
admin.

Last updated: November 12, 2025