# HubSpot Integration Testing Checklist

**Last Updated:** 2026-02-15

Comprehensive testing checklist for verifying HubSpot Forms API v3 and CRM API integrations.

## Automated Testing Scripts

### Configuration and Templates Form

**Script:** `v2/scripts/test-hubspot-config.php` — Token loading, config validation

**Script:** `v2/scripts/test-template-form-submission.php` — Templates form (GUID 11e392f7) direct submission test

```bash
php v2/scripts/test-hubspot-config.php
php v2/scripts/test-template-form-submission.php
```

After running the template test, verify in HubSpot: Marketing > Lead Capture > Forms > Templates > Submissions tab for the test email.

### Comprehensive Form Testing

**Script:** `v2/scripts/hubspot/test-all-forms-comprehensive.php` (if available)

Tests all HubSpot integration forms with diverse scenarios:

- Generates unique test emails per form
- Tests different UTM scenarios (Google Ads, Organic Search, Direct Traffic, Referral, LinkedIn, Meta)
- Captures API responses and contact IDs
- Saves test results to `temp/test-results-{timestamp}.json`

**Usage:**

```bash
php v2/scripts/hubspot/test-all-forms-comprehensive.php --base-url=http://localhost:8003
```

### Contact Verification

**Script:** `v2/scripts/hubspot/verify-contact-data.php`

Verifies test contacts created by comprehensive test script:

- Fetches contacts from HubSpot via CRM API v3
- Compares expected vs actual values for all fields
- Checks UTM parameters, leadSource, and other properties
- Generates detailed verification report

**Usage:**

```bash
php v2/scripts/hubspot/verify-contact-data.php --results-file=temp/test-results-{timestamp}.json
```

**Known Issues (as of 2025-11-15):**

**Fixed:**

- ✅ Created missing `v2/helpers/logger.php` file (fixed HTTP 500 errors)
- ✅ Improved referral detection logic in `export-workdays.php`

**Remaining Issues:**

All endpoints are now working (9/9 successful), but UTM parameters are not being set in HubSpot contacts. This is a **HubSpot form/property configuration issue**, not a code issue.

**Root Cause:** HubSpot forms don't have UTM fields configured, so HubSpot silently ignores them even though the code sends them correctly.

**Affected Forms:**

- All Forms API v3 forms need UTM fields added as hidden fields
- CRM API contacts need UTM properties to exist in HubSpot

**See:** `docs/guides/HUBSPOT_FORM_FIELD_CONFIGURATION.md` for complete form GUID list and field configuration instructions.

**Recommendations:**

1. ✅ **Code fixes completed** - All endpoints working correctly
2. ⏳ **Configure HubSpot forms** - Add UTM fields to all forms (see HUBSPOT_FORM_FIELD_CONFIGURATION.md)
3. ⏳ **Verify HubSpot properties** - Ensure all UTM properties exist
4. ⏳ **Re-test after configuration** - Verify UTM fields are set correctly
5. ⏳ **Browser-based testing** - Test form includes and content pages

## Pre-Deployment Testing

### Forms API v3 Endpoints

#### collect-lead.php

- [ ] Test with valid email and tool data
- [ ] Test with missing hubspotutk cookie
- [ ] Test with hubspotutk in request body only
- [ ] Verify contact created in HubSpot
- [ ] Verify activity timeline shows page views
- [ ] Verify UTM parameters stored correctly
- [ ] Test retry logic (simulate API failure)
- [ ] Verify error handling (invalid email, missing fields)

#### submit-template.php

- [ ] Run `php v2/scripts/test-template-form-submission.php` — direct API test
- [ ] Test template submission with all fields (browser: /vorlagen/schichtplan-excel-vorlage)
- [ ] Test with minimal required fields
- [ ] Verify hubspotutk extraction (cookie-first)
- [ ] Verify context completeness (hutk, pageUri, pageName, ipAddress)
- [ ] Test retry logic
- [ ] Verify contact creation/update in HubSpot Submissions (form GUID 11e392f7)
- [ ] Test submitFormDirectly fallback (UTM/hubspotutk included)

#### addon-request.php

- [ ] Test addon request submission
- [ ] Verify UTM data transmission
- [ ] Verify hubspotutk included
- [ ] Test error handling

#### export-workdays.php

- [ ] Test workdays export submission
- [ ] Verify contact creation
- [ ] Verify activity tracking

#### shiftops-nps.php

- [ ] Test NPS score submission (0-10)
- [ ] Verify hubspotutk extraction
- [ ] Verify context completeness
- [ ] Test retry logic
- [ ] Verify NPS category calculation

#### shiftops-hubspot.php

- [ ] Test ShiftOps data submission
- [ ] Verify large payload handling
- [ ] Verify retry logic
- [ ] Verify contact creation/update

### CRM API Endpoints

#### webinar-registration.php

- [ ] Test webinar registration
- [ ] Verify page view tracking BEFORE contact creation
- [ ] Verify contact creation
- [ ] Verify page view tracking AFTER contact creation
- [ ] Verify UTM parameters stored

#### payroll-webinar-registration.php

- [ ] Test payroll webinar registration
- [ ] Verify page view tracking (before/after)
- [ ] Verify contact creation
- [ ] Verify UTM parameters stored

### JavaScript Integration

#### Cookie Extraction

- [ ] Test `getCookie('hubspotutk')` helper function
- [ ] Test `getHubspotutk()` helper function
- [ ] Verify cookie extraction works across browsers
- [ ] Test fallback when cookie doesn't exist

#### UTM Data Transmission

- [ ] Test `getUTMDataForAPI()` includes hubspotutk
- [ ] Verify UTM data sent in request body
- [ ] Test fallback when utmTracker not available
- [ ] Verify page_url and referrer included

#### Form Submissions

- [ ] Test all tool pages (17+ files)
- [ ] Test template pages (2 files)
- [ ] Test webinar pages (3 files)
- [ ] Test pricing/addon forms (2 files)
- [ ] Verify hubspotutk included in all requests

#### Base Form Includes

- [ ] Test include_form-hs.php form submission
- [ ] Test include_form-hs-sdr.php form submission
- [ ] Test include_form-gated-content.php form submission
- [ ] Test include_form-webinar.php form submission
- [ ] Verify hubspotutk hidden field populated before submission
- [ ] Verify hubspotutk extracted via populateUTMFields() (include_form-hs.php)
- [ ] Verify hubspotutk extracted in submit handler (other includes)
- [ ] Test with hubspotutk cookie present
- [ ] Test without hubspotutk cookie (fallback)
- [ ] Verify hubspotutk appears in POST data to /form-hs
- [ ] Verify html/form-hs.php receives hubspotutk from form field
- [ ] Verify HubSpot contact activity timeline shows page views

### Helper Functions

#### getActualPageUrl()

- [ ] Test with valid page_url from input
- [ ] Test with valid referrer from input
- [ ] Test with HTTP_REFERER
- [ ] Verify never returns API file URL
- [ ] Test with null/empty values

#### getPageNameFromUrl()

- [ ] Test with valid URL
- [ ] Test with empty URL (returns default)
- [ ] Test with API file URL (returns default)
- [ ] Verify file extension stripping
- [ ] Verify readable format conversion

## Post-Deployment Verification

### HubSpot Contact Verification

#### Contact Creation

- [ ] Verify contact created in HubSpot
- [ ] Verify email address correct
- [ ] Verify all form fields stored
- [ ] Verify UTM parameters stored
- [ ] Verify lead source correct

#### Activity Timeline

- [ ] Verify page views appear in timeline
- [ ] Verify form submission appears
- [ ] Verify conversion page tracked
- [ ] Verify session continuity (if hutk present)

#### Attribution Data

- [ ] Verify utm_source stored correctly
- [ ] Verify utm_medium stored correctly
- [ ] Verify utm_campaign stored correctly
- [ ] Verify utm_term stored correctly
- [ ] Verify utm_content stored correctly
- [ ] Verify gclid stored (if present)
- [ ] Verify leadSource correct

### API Response Verification

#### Success Responses

- [ ] Verify HTTP 200 or 204 responses
- [ ] Verify response time acceptable (< 2s)
- [ ] Verify no errors in logs

#### Error Handling

- [ ] Verify retry logic works
- [ ] Verify error messages user-friendly
- [ ] Verify errors logged properly
- [ ] Verify graceful degradation

### Logging Verification

#### Forms API v3 Context Logging

- [ ] Verify hutk presence logged
- [ ] Verify pageUri logged
- [ ] Verify pageName logged
- [ ] Verify ipAddress logged

#### Retry Attempt Logging

- [ ] Verify retry attempts logged
- [ ] Verify HTTP codes logged
- [ ] Verify error messages logged
- [ ] Verify success after retry logged

## Browser/Device Testing

### Desktop Browsers

- [ ] Chrome (latest)
- [ ] Firefox (latest)
- [ ] Safari (latest)
- [ ] Edge (latest)

### Mobile Devices

- [ ] iOS Safari
- [ ] Android Chrome
- [ ] Mobile Firefox

### Test Scenarios

#### With HubSpot Tracking Code

- [ ] Verify hubspotutk cookie set
- [ ] Verify cookie extracted correctly
- [ ] Verify form submission includes hutk
- [ ] Verify activity tracking works

#### Without HubSpot Tracking Code

- [ ] Verify form still works
- [ ] Verify contact created
- [ ] Verify fallback to input parameter
- [ ] Verify graceful degradation

#### Cookie Blocked

- [ ] Test with cookies disabled
- [ ] Verify form still works
- [ ] Verify fallback mechanisms
- [ ] Verify error handling

## Performance Testing

### Response Times

- [ ] Verify API response < 2s (normal)
- [ ] Verify retry logic doesn't cause excessive delays
- [ ] Verify timeout handling (30s)

### Rate Limiting

- [ ] Test with rapid submissions
- [ ] Verify rate limit handling
- [ ] Verify retry logic respects rate limits

## Security Testing

### Input Validation

- [ ] Test with invalid email formats
- [ ] Test with SQL injection attempts
- [ ] Test with XSS attempts
- [ ] Verify sanitization works

### API Security

- [ ] Verify API tokens not exposed
- [ ] Verify HTTPS used
- [ ] Verify input sanitization
- [ ] Verify error messages don't expose internals

## Integration Testing

### End-to-End Flow

- [ ] User visits page with UTM parameters
- [ ] User submits form
- [ ] Verify contact created in HubSpot
- [ ] Verify activity timeline populated
- [ ] Verify UTM parameters stored
- [ ] Verify attribution correct

### Multi-Step Flows

- [ ] Test lead-capture.php two-step flow
- [ ] Verify Step 1 creates contact
- [ ] Verify Step 2 updates contact
- [ ] Verify activity tracking across steps

## Regression Testing

### After Code Changes

- [ ] Re-test all form endpoints
- [ ] Verify no breaking changes
- [ ] Verify backward compatibility
- [ ] Verify helper functions still work

### After HubSpot Updates

- [ ] Verify API endpoints still work
- [ ] Verify field mappings correct
- [ ] Verify form configurations valid

## Monitoring

### Post-Deployment Monitoring (24-48 hours)

#### HubSpot Logs

- [ ] Monitor for API errors
- [ ] Monitor for rate limit issues
- [ ] Monitor for contact creation failures

#### Application Logs

- [ ] Monitor error_log for issues
- [ ] Monitor retry attempt frequency
- [ ] Monitor response times

#### Contact Quality

- [ ] Spot-check contact creation
- [ ] Verify UTM parameters accuracy
- [ ] Verify activity timeline completeness

## Automated Testing Scripts

### Test Script Location

`scripts/hubspot/test-forms-api.php`

### Base Form Includes Test Scenarios

1. **include_form-hs.php Test:**

   - Submit form with hubspotutk cookie present
   - Verify populateUTMFields() extracts hubspotutk
   - Verify hidden field populated
   - Verify POST data includes hubspotutk
   - Verify html/form-hs.php receives hubspotutk

2. **include_form-hs-sdr.php Test:**

   - Submit form with hubspotutk cookie present
   - Verify submit handler extracts hubspotutk
   - Verify hidden field populated
   - Verify POST data includes hubspotutk

3. **include_form-gated-content.php Test:**

   - Submit form with hubspotutk cookie present
   - Verify submit handler extracts hubspotutk
   - Verify hidden field populated
   - Verify POST data includes hubspotutk

4. **include_form-webinar.php Test:**

   - Submit form with hubspotutk cookie present
   - Verify submit handler extracts hubspotutk
   - Verify hidden field populated
   - Verify POST data includes hubspotutk

5. **Missing hubspotutk Cookie Test:**
   - Submit form without hubspotutk cookie
   - Verify fallback cookie extraction works
   - Verify form still submits successfully
   - Verify html/form-hs.php handles missing hubspotutk gracefully

### Test Scenarios

1. **Valid Data Test:**

   - Submit form with all valid fields
   - Verify success response
   - Verify contact created

2. **Missing hutk Test:**

   - Submit form without hubspotutk
   - Verify contact still created
   - Verify activity may not be tracked

3. **Invalid Data Test:**

   - Submit form with invalid email
   - Verify error response
   - Verify no contact created

4. **Retry Logic Test:**
   - Simulate API failure
   - Verify retry attempts
   - Verify eventual success

## Quick Reference

### Critical Fields Checklist

For every Forms API v3 submission, verify:

- [ ] `hutk` in context (from cookie or input)
- [ ] `ipAddress` in context
- [ ] `pageUri` in context (not API file URL)
- [ ] `pageName` in context (readable name)
- [ ] Retry logic implemented (3 attempts)
- [ ] Enhanced logging enabled

### JavaScript Checklist

For every form submission, verify:

- [ ] `hubspotutk` extracted (cookie or helper)
- [ ] `hubspotutk` included in request body
- [ ] UTM data included
- [ ] `page_url` included
- [ ] `referrer` included

### Verification Commands

```bash
# Test specific endpoint
curl -X POST http://localhost:8003/v2/api/collect-lead.php \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","tool_name":"Test Tool"}'

# Check HubSpot contact (requires API token)
php scripts/hubspot/hubspot-contact-audit.php test@example.com

# View logs
tail -f v2/logs/hubspot-*.log
```

## Common Issues and Solutions

### Issue: Contact Created But No Page Views

**Check:**

1. Is `hutk` in context?
2. Is `hutk` value valid?
3. Was page view tracked before contact creation?

**Solution:** Ensure `hutk` is extracted from cookie and included in context.

### Issue: UTM Parameters Missing

**Check:**

1. Are UTM fields included in request?
2. Do field names match HubSpot properties?
3. Is form configured with UTM fields?

**Solution:** Verify UTM data sent and form field configuration.

### Issue: Retry Logic Not Working

**Check:**

1. Is HTTP status code check correct (200 or 204)?
2. Is retry delay increasing?
3. Is error permanent or transient?

**Solution:** Review retry logic implementation and error logs.