UI-licious Documentation

Appearance

Testing Shopify Storefronts ​

When running automated UI tests on a Shopify store, Shopify's bot mitigation systems may flag automated browser sessions. This can result in rate-limiting errors (HTTP 429), CAPTCHA challenges, or blocked requests.

Shopify provides Web Bot Auth, a mechanism based on HTTP message signatures that authorizes automated testing tools and crawlers to access your online storefront.

By generating a signature in your Shopify Admin and adding it as global request headers in UI-licious, your automated tests can navigate and interact with your storefront without being blocked.

Step 1: Generate Signatures in Shopify Admin ​

You create and manage Web Bot Auth signatures directly in your Shopify Admin:

  1. In your Shopify Admin, navigate to Online Store > Preferences.
  2. Scroll to the Crawler access section and click Create signature.
  3. In the Name field, enter a descriptive label (such as UI-licious Storefront Tests).
  4. In the Domain field, select the connected domain you want to test.
  5. In the Valid for section, choose an expiration period (up to 3 months).
  6. Click Create.
  7. Click Copy next to each value to retrieve your signature headers.

Required HTTP Headers ​

Each signature consists of 3 HTTP headers that must be sent with every request:

Header NameDescription
Signature-InputCryptographic signature input string generated by Shopify.
SignatureCryptographic signature value generated by Shopify.
Signature-AgentThe agent URI string. Must be "https://shopify.com" (including quotes).

Signature-Agent Formatting

The Signature-Agent value must include literal quotation marks around the URL: "https://shopify.com". In configuration files or test scripts, make sure to escape or quote it properly (e.g. '"https://shopify.com"' or "\"https://shopify.com\"").

Step 2: Add Headers to UI-licious ​

You can configure these headers in your UI-licious project configuration or directly within test scripts.

If you run multiple tests against your Shopify storefront, define the headers in your project configuration file (uilicious.config.yaml or uilicious.config.json). This ensures the headers are attached to every test session automatically without repeating code across test files.

In uilicious.config.yaml:

yaml
# uilicious.config.yaml
headers:
  Signature-Input: "sig1=(...);created=...;keyid=..."
  Signature: "sig1=:...=:"
  Signature-Agent: "\"https://shopify.com\""

In uilicious.config.json:

json
{
  "headers": {
    "Signature-Input": "sig1=(...);created=...;keyid=...",
    "Signature": "sig1=:...=:",
    "Signature-Agent": "\"https://shopify.com\""
  }
}

Option B: In a Test Script ​

You can also set the headers dynamically at the beginning of a test script using TEST.setRequestHeaders():

js
// Attach Shopify Web Bot Auth headers before navigating
TEST.setRequestHeaders({
  "Signature-Input": "sig1=(...);created=...;keyid=...",
  "Signature": "sig1=:...=:",
  "Signature-Agent": '"https://shopify.com"'
})

// Navigate to the storefront
I.goTo("https://your-store.com")
I.see("Featured Collection")
I.click("Featured Collection")

Because UI-licious applies these headers at the proxy level, they automatically accompany all top-level navigations, sub-resources (CSS, JS, images), and background API requests.

Important Considerations ​

  • Storefront Only (No Checkout Access): Signatures authorize access only to the public online storefront. They do not grant access to Shopify Checkout (/checkouts/), which enforces separate security controls.
  • Expiration: Signatures expire after a maximum of 3 months and cannot be renewed in place. When a signature expires, generate a new one in Shopify Admin and update your configuration.
  • Domain Scoping: Each signature is valid only for the specific domain selected during creation. If your store uses multiple domains, create and configure a signature for each domain.

Troubleshooting ​

If your tests encounter HTTP 429 errors or bot challenge pages:

  • Check Expiration: In Shopify Admin under Online Store > Preferences, verify that your signature status is still active.
  • Verify All 3 Headers: Confirm that Signature-Input, Signature, and Signature-Agent are all present on the request.
  • Verify Quotes on Signature-Agent: Check that the Signature-Agent header value literally includes quotation marks around the URL ("https://shopify.com").
  • Check the Domain: Ensure the URL in your test script matches the exact domain chosen when creating the signature in Shopify Admin.