SureCart Testing Guide

This guide explains how to safely test SureCart checkout flows with Flowguard without creating real orders or processing real payments.

Before You Start

Always enable Test Mode before testing SureCart flows! Without Test Mode, real orders will be created and payments will be processed through SureCart's system.

Overview

SureCart presents unique challenges for automated testing due to its modern architecture. Flowguard has been specifically designed to handle these challenges seamlessly.

Technical Challenges Solved by Flowguard

Challenge	Description	Flowguard Solution
Shadow DOM	SureCart uses Web Components with Shadow DOM, making elements invisible to standard selectors	Automatic Shadow DOM traversal - the Selector Picker and test runner pierce through shadow boundaries
SaaS Architecture	SureCart is a cloud-based service with API calls to external servers	Intelligent API interception - blocks order-creating endpoints while allowing cart/checkout functionality
Real-time State	Checkout state is managed server-side via API	Session-aware test mode that maintains cart persistence across page navigations

Test Mode Protections

When Test Mode is enabled, Flowguard provides comprehensive protection:

Protection	What It Does
No Real Orders	Checkout finalization blocked at API level
No Payment Processing	Payment intents intercepted before Stripe/PayPal
Automatic Sandbox Mode	Forces SureCart to use test/sandbox payment processors
Cart Preservation	Shopping cart works normally during testing
Customer Safety	No customer accounts or data created in SureCart
Email Prevention	Order confirmation emails blocked

Automatic Payment Mode Switching

Works Even in Live Mode

When your SureCart store is configured for live payments (Stripe, PayPal, etc.), Flowguard automatically switches to test/sandbox mode during test runs. You don't need to manually toggle SureCart's test mode.

This means:

• In the Flow Editor preview: Payment forms use sandbox mode
• During flow execution: Stripe/PayPal use test credentials
• For real customers: Normal live payment processing (unaffected)

Scenario	SureCart Mode	Result
Flowguard test running	Forced to Test	Sandbox payments
Flow Editor iframe	Forced to Test	Sandbox payments
Regular customer visit	Live (unchanged)	Real payments

This automatic switching ensures your tests work identically whether your store is in test or live mode, without any manual configuration.

How It Works

Shadow DOM Support

SureCart's checkout forms are built using Web Components with Shadow DOM encapsulation. Traditional CSS selectors cannot reach elements inside shadow roots.

Flowguard automatically handles this:

1. Selector Picker: When you use the Selector Picker in the Flow Editor, it automatically detects and traverses shadow boundaries
2. Test Execution: Playwright pierces shadow DOM by default, so your recorded selectors work seamlessly
3. No Special Syntax: You don't need to use any special selector syntax - just point and click

Shadow DOM is Invisible to You

You don't need to know or care about Shadow DOM when using Flowguard. The Selector Picker and test runner handle it automatically. Just click on elements and Flowguard finds them.

API Request Handling

SureCart communicates with its cloud backend via REST API calls. Flowguard intelligently manages these:

Allowed Requests (for normal cart/checkout functionality):

• Creating and updating checkouts
• Adding/removing line items
• Fetching product information
• Loading checkout forms
• Customer address validation

Blocked Requests (to prevent real orders):

• /v1/checkouts/{id}/finalize - Payment processing
• /v1/checkouts/{id}/manually_pay - Manual order creation
• WordPress REST API /confirm endpoint

When these endpoints are blocked, Flowguard returns realistic fake responses so the checkout flow appears to complete normally.

Setting Up Test Mode

Enable Test Mode

1. Navigate to Flowguard → Settings → Test Mode
2. Enable the Test Mode toggle
3. Configure email handling (Block or Rewrite)
4. Save settings

Verify SureCart Detection

Flowguard automatically detects SureCart and applies appropriate protections. You can verify this in the test logs after running a flow - look for surecart entries showing blocked API calls.

Select Test Payment Provider

Important: Use Test Payment Provider

When creating your test flows, you must select the Test Payment provider in the checkout. Flowguard forces SureCart into test mode, which makes the Test Payment option available even when your store is configured for live payments.

This ensures:

• No real payment processing occurs
• The checkout completes with a simulated success
• Your flow tests the full checkout journey safely

Creating SureCart Flows

Example Flow: Complete Checkout

1. Open Page
   - URL: https://yoursite.com/products/your-product

2. Click (Add to Cart / Buy Now)
   - Selector: sc-product-buy-button

3. Wait
   - Time: 2000

4. Open Page
   - URL: https://yoursite.com/checkout

5. Wait (Checkout Load)
   - Time: 2000

6. Type Text (Email)
   - Selector: sc-checkout input[name="email"]
   - Value: test@example.com

7. Type Text (First Name)
   - Selector: sc-checkout input[name="first_name"]
   - Value: John

8. Type Text (Last Name)
   - Selector: sc-checkout input[name="last_name"]
   - Value: Doe

9. Click (Select Test Payment)
   - Selector: sc-payment-method-choice[processor-id="test"]

10. Wait
    - Time: 500

11. Click (Submit Order)
    - Selector: sc-checkout sc-order-submit

12. Wait (Processing)
    - Time: 3000

13. Check (Assert Success)
    - Selector: sc-dialog
    - Expected: "Test checkout successful"

Success Modal After Checkout

Test Checkout Success Modal

When the checkout completes in test mode, SureCart displays a modal dialog (in the case you've not set a redirect url). The modal contains test-specific messaging.

Expected modal content:

Element	Text
Title	"Test checkout successful!"
Message	"This is a simulated test checkout, and no orders were processed. To perform a test order, please contact your store administrator"
Button	"Go to homepage"

For your Assert step, use one of these approaches:

# Option 1: Check for the modal dialog
Check (Assert Success Modal)
- Selector: sc-dialog
- Expected: "Test checkout successful"

# Option 2: Check for specific text
Check (Assert Success Text)
- Selector: sc-dialog-header
- Expected: "Test checkout successful"

If Your Assertion Fails

If your Check step fails, look at the screenshot in the test results. The screenshot shows exactly what text appeared on screen - use that text in your assertion. SureCart may update their modal text in future versions.

Common SureCart Selectors

SureCart uses custom HTML elements (Web Components). Here are typical selectors:

Product Pages

• Buy button: sc-product-buy-button, sc-buy-button
• Add to cart: sc-product-buy-button[type="add-to-cart"]
• Quantity: sc-product-quantity input
• Price display: sc-product-price

Checkout Form

• Email: sc-checkout input[name="email"]
• Name fields: sc-checkout input[name="first_name"], input[name="last_name"]
• Address: sc-checkout input[name="line_1"]
• City: sc-checkout input[name="city"]
• Submit button: sc-order-submit, sc-checkout-form-submit

Order Confirmation

• Confirmation container: sc-order-confirmation
• Order number: sc-order-confirmation .order-number

Selectors May Vary

SureCart occasionally updates their component structure. If a selector doesn't work, use the Selector Picker to find the current selector for your element.

Testing Scenarios

Guest Checkout

1. Add product to cart
2. Navigate to checkout
3. Fill customer information
4. Submit order
5. Verify confirmation appears

In Test Mode, the checkout appears to complete but no order is created in SureCart.

Coupon/Discount Testing

1. Add product to cart
2. Navigate to checkout
3. Enter discount code
4. Verify discount applies
5. Complete checkout

Coupons validate normally - Flowguard only blocks the final order creation.

Subscription Products

SureCart subscription products work the same way:

1. Select subscription product
2. Complete checkout form
3. Submit order

In Test Mode, no subscription is created, but the flow completes as if it did.

What's Blocked in Test Mode

SureCart API Calls

✅ Blocked:

• Checkout finalization (/finalize)
• Manual payment processing (/manually_pay)
• Order confirmation (/confirm)

✅ Allowed:

• Checkout creation and updates
• Line item management
• Product/price fetching
• Customer information validation

WordPress Operations

✅ Blocked:

• Post creation (orders synced to WordPress)
• User creation (customer accounts)
• Email sending

Reviewing Test Results

After running a SureCart flow:

1. Go to Flowguard → Flows
2. Click on your flow
3. View the Test Logs tab

SureCart-Specific Logs

Look for entries with type surecart:

{
  "type": "surecart",
  "action": "blocked",
  "endpoint": "finalize",
  "checkout_id": "abc123...",
  "note": "SureCart checkout finalization blocked in test mode"
}

This confirms the order was not created.

Troubleshooting

Elements Not Found

Problem: Flow fails to find SureCart elements

Solutions:

1. Add a Wait step before the interaction (SureCart loads dynamically)
2. Use the Selector Picker to get the current selector
3. Check if SureCart updated their component structure

Checkout Hangs on "Submitting"

Problem: Checkout appears stuck after clicking submit

Solutions:

1. Verify Test Mode is enabled
2. Check test logs for blocked API calls
3. Ensure your flow has adequate wait times

Cart Empty After Navigation

Problem: Cart empties when navigating between pages

Solutions:

1. Verify preview token is active (Flow Editor should show the token)
2. Add Wait steps between page navigations
3. Check browser console for errors

Flow Works in Preview But Fails in Execution

Problem: Flow succeeds in the editor preview but fails when run

Solutions:

1. Ensure all wait times are adequate
2. Check that selectors don't depend on logged-in user state
3. Review the execution screenshots for what's actually on screen

Best Practices

1. Always Enable Test Mode

Critical

Never run SureCart checkout flows without Test Mode. Real orders will be created and payments processed!

2. Use Adequate Wait Times

SureCart loads content dynamically. Recommended waits:

• After page navigation: 2000ms
• After clicking buy button: 1500ms
• After form submission: 3000ms

3. Test in Preview First

Use the Flow Editor's live preview to verify each step works before running the full flow.

4. Monitor Test Logs

After each test run, check the logs to confirm:

• [ ] SureCart API calls were properly blocked
• [ ] No orders appear in SureCart dashboard
• [ ] Checkout flow completed visually

5. Use Descriptive Step Names

✅ Good	❌ Bad
"Click (Buy Now Button)"	"Click"
"Fill (Customer Email)"	"Type"
"Wait (Checkout Loading)"	"Wait"

Compatibility

SureCart Versions

Flowguard's SureCart integration is compatible with:

• SureCart 2.x and later
• All SureCart checkout form types
• Instant Checkout pages
• Embedded checkout forms

Payment Processors

Works with all SureCart payment processors:

• Stripe
• PayPal
• Manual/offline payments

All payment processing is blocked in Test Mode regardless of processor.

Related Documentation

• Test Mode Guide
• WooCommerce Testing
• Flow Editor Guide
• Step Types Reference