# Quick Start Guide - Tracking Validation Suite


**Last Updated:** 2025-11-20

## Overview

This validation suite tests the updated tracking setup by simulating form submissions and page flows against actual HubSpot contact data from November 1-14, 2025.

## Prerequisites

1. **HubSpot API Token:** Set `HUBSPOT_API_TOKEN` environment variable or configure in `v2/config/hubspot.php`
2. **PHP 7.4+:** Required for running scripts
3. **Directory Permissions:** Ensure `scripts/temp/` is writable

## Quick Run

Run the complete validation suite:

```bash
php scripts/development/testing/run-full-validation.php 2025-11-01 2025-11-14
```

This will:
1. Fetch contacts from HubSpot (Nov 1-14, 2025)
2. Normalize the data
3. Simulate all tracking flows
4. Compare results
5. Generate analysis and reports

## Output

Results are written to:
- **Intermediate files:** `scripts/temp/`
- **Final report:** `docs/development/testing/validation-results-YYYYmmdd-HHMMSS/`

## What Gets Tested

### Lead Source Determination
- Paid Search detection (requires `gclid` + `utm_source`)
- Organic Search detection
- Meta traffic validation
- Broken/old page heuristics
- Referrer validation

### Form Submission Tracking
- Lead capture forms
- Template downloads
- Add-on requests
- Webinar registrations
- Export workdays
- ShiftOps submissions
- Collect lead submissions

### Page Flow Tracking
- User journey reconstruction
- Lead source changes throughout session
- Page type inference

## Understanding Results

### Expected Discrepancies
These are **improvements** where new logic correctly fixes old misclassifications:
- Paid Search → Organic Search (when `utm_source` missing)
- Meta → Organic Search (when referrer is search engine)
- Content value simplifications (removed prefixes/suffixes)

### Unexpected Discrepancies
These require review:
- Lead source mismatches
- Sign up type mismatches
- Content value mismatches
- UTM parameter mismatches

## Review Process

1. **Check Summary:** Review `00-summary.json` for overall statistics
2. **Analyze Discrepancies:** Review `07-discrepancy-analysis.json` for detailed findings
3. **Read Report:** Review `TRACKING_VALIDATION_REPORT_NOV_2025.md` for comprehensive analysis
4. **Review Test Cases:** Check `TRACKING_TEST_CASES.md` for expected behaviors

## Troubleshooting

### No Contacts Found
- Verify date range (Nov 1-14, 2025)
- Check HubSpot API token is configured
- Verify API token has read permissions

### Page Views Not Found
- This is normal - page views require `vid` (legacy ID)
- Script will gracefully skip if `vid` not available
- Analytics data (first/last URLs) will still be used

### Form Submissions Not Found
- Form submissions are optional data
- Script will work with available data
- Focus on lead source and form type matching

## Next Steps After Validation

1. **Review Findings:** Identify any unexpected discrepancies
2. **Fix Issues:** Update code if issues found
3. **Re-run Validation:** Verify fixes work correctly
4. **Document Changes:** Update test cases if needed

## Manual Testing

You can also run individual steps:

```bash
# Step 1: Fetch contacts
php scripts/hubspot/fetch-contacts-by-date.php 2025-11-01 2025-11-14

# Step 2: Normalize data
php scripts/hubspot/normalize-contact-data.php

# Step 3: Simulate lead source
php scripts/development/testing/simulate-lead-source.php

# Step 4: Simulate form submissions
php scripts/development/testing/simulate-form-submission.php

# Step 5: Simulate page flows
php scripts/development/testing/simulate-page-flow.php

# Step 6: Compare results
php scripts/development/testing/compare-tracking-results.php

# Step 7: Analyze discrepancies
php scripts/development/testing/analyze-discrepancies.php
```

## Support

For issues or questions:
1. Check `scripts/development/testing/README.md` for detailed documentation
2. Review `docs/development/testing/TRACKING_TEST_CASES.md` for expected behaviors
3. Check script output for error messages