Skip to main content

Documentation Index

Fetch the complete documentation index at: https://flowdeck.studio/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
flowdeck test

Run unit and UI tests. 
# After 'flowdeck config set', run tests with saved settings
flowdeck test

# Run all tests (without config set)
flowdeck test -w MyApp.xcworkspace -s MyScheme -S "iPhone 16"

# Run tests on macOS
flowdeck test -D "My Mac"

# Run specific tests with --only
flowdeck test --only MyTests/LoginTests
flowdeck test --only MyTests/LoginTests/testLogin
flowdeck test --only "MyTests/Login Tests/test Login Success"

# Skip specific tests
flowdeck test --skip MyTests/SlowTests
flowdeck test --skip MyTests/IntegrationTests

# Multiple test targets
flowdeck test --test-targets "UnitTests,IntegrationTests"

# Run a specific test plan (name or path)
flowdeck test --plan "Smoke"
flowdeck test --plan "TestPlans/Smoke.xctestplan"

# Output modes
flowdeck test                  # Summary only (default)
flowdeck test -v               # Verbose xcodebuild output
flowdeck test --progress       # Show pass/fail as tests complete
flowdeck test --streaming      # Clean output for file capture
flowdeck test --json           # JSON for CI/automation

# Pass arguments to xcodebuild
flowdeck test --xcodebuild-options='-parallel-testing-enabled YES'
flowdeck test --xcodebuild-options='-enableCodeCoverage YES'
flowdeck test --xcodebuild-options='-resultBundlePath /tmp/results.xcresult'
flowdeck test --xcodebuild-env='CI=true'

# Show usage examples
flowdeck test --examples

​
Options

OptionShortDescription
--examplesShow usage examples
--project <path>-pProject directory
--workspace <path>-wPath to workspace (.xcworkspace) or project (.xcodeproj)
--scheme <name>-sScheme name
--configuration <name>-CBuild configuration (Debug/Release)
--simulator <name>-SSimulator name/UDID (REQUIRED for iOS/tvOS/watchOS)
--device <name>-DDevice name/UDID (use “My Mac” for macOS)
--derived-data-path <path>-dDerived data path (default: ~/Library/Developer/FlowDeck/DerivedData)
--config <path>-cPath to an explicit command config file
--test-targets <targets>Specific test targets to run (comma-separated)
--test-cases <cases>Specific test cases to run (comma-separated, format: TargetName/ClassName/testMethod)
--only <tests>Run only specific tests (format: TargetName/ClassName or TargetName/ClassName/testMethod)
--skip <tests>Skip specific tests (format: TargetName/ClassName or TargetName/ClassName/testMethod)
--plan <name-or-path>Test plan name or .xctestplan path
--json-jOutput as JSON
--verbose-vShow raw xcodebuild test output (beautified)
--progressShow test results as they complete (pass/fail per test)
--streamingStream clean formatted test results (no escape codes, for file capture)
--xcodebuild-options <args>Extra xcodebuild arguments (e.g., --xcodebuild-options='-parallel-testing-enabled YES')
--xcodebuild-env <vars>Xcodebuild environment variables (e.g., ‘CI=true’)
After running flowdeck config set, workspace, scheme, and simulator are saved to project state. CLI parameters are only required if you haven’t run flowdeck config set, or to override saved values. Use --device "My Mac" for macOS builds.
--config here means the explicit command config file format. It is separate from .flowdeck/config.json and .flowdeck/config.local.json.
On failed test runs, FlowDeck prints the extracted failure reason plus Full log: <absolute-path> for the persisted raw xcodebuild output. Read that file directly before rerunning with --verbose.

​
Test Filtering

The --only option supports multiple formats:
  • Full path: MyAppTests/LoginTests/testValidLogin - runs a specific test method
  • Class name: LoginTests - runs all tests in that class
  • Method name: testValidLogin - runs all tests with that method name (across classes)
You can specify multiple tests by using --only multiple times or separating with commas.

​
Config File Format

The --config parameter accepts the explicit command config format: 
{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "configuration": "Debug",
  "platform": "iOS",
  "version": "18.0",
  "derivedDataPath": "/custom/path"
}
For macOS builds, set platform to "macOS" (no simulator needed).

​
JSON Output

When using --json, the command outputs newline-delimited JSON events during execution, followed by a final test result: 
{"type":"status","stage":"COMPILING","message":"Building for testing..."}
{"type":"status","stage":"TESTING","message":"Running tests on iPhone 16..."}
{"type":"test_started","testName":"LoginTests/testValidLogin"}
{"type":"test_passed","testName":"LoginTests/testValidLogin","duration":0.023}
{"type":"test_failed","testName":"LoginTests/testInvalidLogin","duration":0.045,"reason":"XCTAssertEqual failed","file":"LoginTests.swift","line":42}
{"type":"result","success":false,"operation":"test"}
Event Types:
TypeDescription
statusProgress updates with stage and message
test_startedTest execution started with testName
test_passedTest passed with testName and duration
test_failedTest failed with testName, duration, reason, file, line
test_skippedTest skipped with testName and optional reason
resultFinal result with success and operation
Final Result (Success): 
{
  "success": true,
  "totalTests": 42,
  "passedTests": 42,
  "failedTests": 0,
  "skippedTests": 0,
  "duration": 12.5,
  "passedTestNames": ["LoginTests/testValidLogin", "..."],
  "skippedTestNames": [],
  "failures": []
}
Final Result (Failure): 
{
  "success": false,
  "totalTests": 42,
  "passedTests": 40,
  "failedTests": 2,
  "skippedTests": 0,
  "duration": 15.3,
  "passedTestNames": ["..."],
  "skippedTestNames": [],
  "failures": [
    {
      "testName": "LoginTests/testInvalidLogin",
      "reason": "XCTAssertEqual failed: (\"expected\") is not equal to (\"actual\")",
      "fileName": "LoginTests.swift",
      "lineNumber": 42,
      "duration": 0.045
    }
  ]
}

​
flowdeck test discover

Discover all available tests in a project by parsing test source files. This uses static source analysis (like Xcode’s Test Navigator) and does not require building the project. 
# After 'flowdeck config set', discover tests with saved settings
flowdeck test discover

# Discover tests (without config set)
flowdeck test discover -w MyApp.xcworkspace -s MyScheme

# Output as JSON (for tooling)
flowdeck test discover --json

# Filter tests by name
flowdeck test discover --filter Login
flowdeck test discover -F Login

# Include tests that are skipped in the scheme or test plan
flowdeck test discover --include-skipped-tests

​
Options

OptionShortDescription
--project <path>-pProject directory
--workspace <path>-wPath to workspace (.xcworkspace) or project (.xcodeproj) (also accepts --ws)
--scheme <name>-sScheme name (also accepts --sch)
--config <path>-cPath to an explicit command config file (also accepts --cfg)
--filter <query>-FFilter tests by name (case-insensitive)
--json-jOutput as JSON
--include-skipped-testsInclude tests that are skipped in the scheme or test plan (marked as skipped)
--examples-eShow usage examples
Test discovery uses static source parsing and doesn’t require building. It finds XCTestCase subclasses, test* methods, @Suite structs, and @Test functions directly from source files. By default, tests that are disabled in the scheme or test plan are excluded from results.

​
JSON Output

{
  "schema": "flowdeck.test",
  "schemaVersion": "1.0.0",
  "tests": [
    {
      "target": "MyAppTests",
      "class": "LoginTests",
      "method": "testValidLogin",
      "identifier": "MyAppTests/LoginTests/testValidLogin",
      "file": "LoginTests.swift",
      "filePath": "/path/to/LoginTests.swift",
      "lineNumber": 15,
      "isSkipped": false
    }
  ]
}

​
flowdeck test plans

List test plans referenced by a scheme. This reads the scheme file and does not build the project. 
# After 'flowdeck config set', list plans with saved settings
flowdeck test plans

# List plans (without config set)
flowdeck test plans -w MyApp.xcworkspace -s MyScheme

# Output as JSON (for tooling)
flowdeck test plans --json

​
Options

OptionShortDescription
--project <path>-pProject directory
--workspace <path>-wPath to workspace (.xcworkspace) or project (.xcodeproj) (also accepts --ws)
--scheme <name>-sScheme name (also accepts --sch)
--config <path>-cPath to an explicit command config file (also accepts --cfg)
--json-jOutput as JSON
--examples-eShow usage examples

​
JSON Output

{
  "schema": "flowdeck.test",
  "schemaVersion": "1.0.0",
  "plans": [
    {
      "name": "Smoke",
      "reference": "container:App/TestPlans/Smoke.xctestplan",
      "path": "/path/to/App/TestPlans/Smoke.xctestplan",
      "isDefault": true,
      "isMissing": false
    }
  ]
}