Swift Package · iOS 17+ · macOS 14+

Generate realistic HealthKit
running data for testing
& development

A Swift Package that produces physiologically accurate outdoor and indoor running workouts — complete with GPS routes, heart rate curves, cadence, splits, and elevation profiles.

View on GitHub Quick Start →

// Package.swift
.package(url: "https://github.com/mps/healthkit-run-generator", from: "0.1.0")

102

Unit Tests

Metrics per Run

Run Profiles

Fitness Levels

Everything you need for realistic test data

From single runs to full training plans — every metric is physiologically calibrated and deterministically reproducible.

🗺️

Outdoor Runs

GPS route generation with elevation profiles, terrain-aware pacing, and realistic coordinate sequences. Rolling hills, flat courses, or hilly terrain.

🏋️

Indoor Runs

Treadmill simulation with incline support, progressive grade profiles, and accurate indoor metrics — no GPS data, just like real treadmill workouts.

❤️

Physiological Accuracy

Heart rate curves follow real exercise physiology — warm-up ramp, steady state, cardiac drift, and effort-based spikes. Cadence correlates with pace.

📊

Run Profiles

Easy, tempo, interval, long run, and race presets. Each profile generates appropriate pace distributions, heart rate zones, and effort patterns.

🔁

Deterministic Seeds

Seed-based generation produces identical results every time. Perfect for snapshot testing, CI pipelines, and reproducible test suites.

📅

Training Plans

Generate realistic 4-week periodized training cycles with progressive overload, recovery weeks, and race-distance-calibrated volume.

📦

Batch Generation

Generate hundreds of runs at once with seed ranges, configuration profiles, and filtering. Export to JSON for use anywhere.

🏅

Fitness Levels

Beginner through Elite with calibrated metric ranges. Each level produces appropriate paces, heart rates, cadence, and caloric burn.

Comprehensive metric coverage

Every metric your HealthKit integration needs — generated with physiologically realistic values.

Metric	Outdoor	Indoor
Distance	✓	✓
Duration	✓	✓
Heart Rate	✓	✓
Cadence	✓	✓
Pace (per split)	✓	✓
Calories	✓	✓
GPS Route	✓	—
Elevation	✓	—
Incline	—	✓

Data that looks real because it is

Generated metrics follow real-world exercise physiology patterns.

Heart Rate Curve — 5mi Easy Run

Intermediate

Heart Rate (bpm) Zone 2 ceiling

Mile Splits — Tempo Run

Advanced

Pace (min/mi) Target pace

Get started in minutes

Clean, expressive API designed for Swift developers.

import HealthKitRunGenerator
import HealthKit

let generator = OutdoorRunGenerator()

// Generate an easy outdoor 5-mile run
let config = RunConfiguration(
    profile: .easyRun,
    fitnessLevel: .intermediate,
    distance: .miles(5),
    terrain: .rolling
)

let workout = try await generator.generate(config: config)
// → HKWorkout + route + heart rate + cadence samples

let batch = BatchRunGenerator()

// Generate 100 runs with deterministic seeds
let runs = batch.generate(
    seedRange: 1...100,
    profile: .easyRun,
    fitnessLevel: .intermediate,
    distance: .miles(5)
)

// Filter by distance and profile
let filter = BatchRunGenerator.FilterOptions(
    minDistanceMiles: 3.0,
    maxDistanceMiles: 8.0,
    profiles: [.tempoRun, .intervalRun]
)

// Export to JSON
if let jsonData = BatchRunGenerator.toJSONData(runs) {
    try jsonData.write(to: URL(fileURLWithPath: "runs.json"))
}

let planner = TrainingPlanGenerator()

// Generate a half-marathon training block
let plan = planner.generate(
    fitnessLevel: .intermediate,
    goalDistance: .halfMarathon,
    baseSeed: 42
)

print(plan.totalMileage)           // 119.1 miles
print(plan.weeklyMileage)          // [30.0, 32.4, 34.5, 22.5]
print(plan.intensityDistribution)  // easy: 55%, tempo: 15%...

// Iterate by week
for week in 0..<4 {
    let weekRuns = plan.runsForWeek(week)
    for scheduled in weekRuns {
        print("Day \(scheduled.dayIndex + 1): \(scheduled.purpose)")
    }
}

// Quick generation with sensible defaults
let easyRun = try await OutdoorRunGenerator.easyRun(
    miles: 3,
    level: .beginner
)

let tempoRun = try await OutdoorRunGenerator.tempoRun(
    miles: 5,
    level: .intermediate
)

let longRun = try await OutdoorRunGenerator.longRun(
    miles: 13,
    level: .advanced
)

// Indoor treadmill run
let treadmill = IndoorRunGenerator()
let config = RunConfiguration(
    profile: .tempoRun,
    fitnessLevel: .advanced,
    distance: .miles(4),
    inclineProfile: .progressive(maxGrade: 3.0)
)
let workout = try await treadmill.generate(config: config)

Training plan generation

Realistic 4-week periodized cycles calibrated by fitness level and goal distance.

Goal	Beginner	Intermediate	Advanced	Elite
5K	12 mi/wk · 4 runs	20 mi/wk · 5 runs	30 mi/wk · 5 runs	40 mi/wk · 6 runs
10K	15 mi/wk · 4 runs	25 mi/wk · 5 runs	35 mi/wk · 5 runs	50 mi/wk · 6 runs
Half Marathon	20 mi/wk · 4 runs	30 mi/wk · 5 runs	45 mi/wk · 5 runs	60 mi/wk · 6 runs
Marathon	25 mi/wk · 4 runs	35 mi/wk · 5 runs	55 mi/wk · 5 runs	75 mi/wk · 6 runs

Configuration Profiles

Easy Week Threshold Week Long Run Focused Speed Work Recovery Week Balanced

Clean, composable API

Four generators cover every use case — from a single test run to a full training cycle.

OutdoorRunGenerator

Generates outdoor runs with GPS routes and elevation profiles.

IndoorRunGenerator

Generates treadmill runs with incline support — no GPS, realistic indoor metrics.

BatchRunGenerator

Generates N runs with seed ranges, config profiles, filtering, and JSON export.

TrainingPlanGenerator

Creates 4-week periodized training cycles with progressive overload.

Stop hand-crafting test data.

Add HealthKit Run Generator to your project and get realistic running workouts in a single function call.

View on GitHub Read the Docs →

.package(url: "https://github.com/mps/healthkit-run-generator", from: "0.1.0")