Skip to main content
FlowDeck CLI provides comprehensive test execution capabilities, making it easy to run tests from the terminal or integrate into CI/CD pipelines.

​
Quick Start

After running flowdeck init, workspace, scheme, and simulator are saved to project state. Run tests with: 
flowdeck test

​
Running All Tests

# With saved settings (after init)
flowdeck test

# Or specify settings directly
flowdeck test -w MyApp.xcworkspace -s MyScheme -S "iPhone 16"

​
Running Tests on macOS

Use --device "My Mac" for macOS-only test targets: 
flowdeck test -D "My Mac"

​
Filtering Tests

​
By Test Target

Run specific test targets: 
flowdeck test --test-targets MyAppTests

# Multiple targets
flowdeck test --test-targets "MyAppTests,MyAppUITests"

​
By Test Class or Method

The --only option supports flexible matching: 
# Run all tests in a target/class
flowdeck test --only MyAppTests/LoginTests

# Run a specific test method
flowdeck test --only MyAppTests/LoginTests/testValidLogin

# Full test path with spaces (use quotes)
flowdeck test --only "MyAppTests/Login Tests/test Login Success"

​
Skipping Tests

Skip specific tests: 
flowdeck test --skip MyAppTests/SlowIntegrationTests
flowdeck test --skip MyAppTests/IntegrationTests

​
Test Plans

Run a specific test plan by name or by path: 
flowdeck test --plan "Smoke"
flowdeck test --plan "TestPlans/Smoke.xctestplan"

​
List Test Plans

List test plans referenced by a scheme (no build required): 
# After init
flowdeck test plans

# Explicit parameters
flowdeck test plans -w MyApp.xcworkspace -s MyScheme

# JSON output for tooling
flowdeck test plans --json

​
Test Discovery

Discover all available tests before running. Test discovery uses static source parsing (like Xcode’s Test Navigator) and does not require building the project. 
# After init, discover tests with saved settings
flowdeck test discover

# Or specify settings directly
flowdeck test discover -w MyApp.xcworkspace -s MyScheme

# JSON format for tooling
flowdeck test discover --json

# Filter 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
By default, tests that are disabled in the scheme or test plan are excluded from discovery results. Use --include-skipped-tests to show them (marked as skipped in the output). Example output: 
🧪 Tests in MyScheme

LoginTests
  - testValidLogin LoginTests.swift:23
  - testInvalidPassword LoginTests.swift:45

CartTests
  - testAddItem CartTests.swift:12
  - testRemoveItem CartTests.swift:34

Total: 4 test(s) in 2 class(es)
With --include-skipped-tests: 
🧪 Tests in MyScheme

LoginTests
  - testValidLogin LoginTests.swift:23
  - testInvalidPassword LoginTests.swift:45
  - testSlowIntegration LoginTests.swift:67 (skipped)

CartTests
  - testAddItem CartTests.swift:12
  - testRemoveItem CartTests.swift:34

Total: 5 test(s) in 2 class(es) (1 skipped)
JSON output with skipped tests: 
{
  "tests": [
    {
      "target": "MyAppTests",
      "class": "LoginTests",
      "method": "testSlowIntegration",
      "identifier": "MyAppTests/LoginTests/testSlowIntegration",
      "file": "LoginTests.swift",
      "filePath": "/path/to/LoginTests.swift",
      "lineNumber": 67,
      "isSkipped": true
    }
  ]
}

​
JSON Output

For CI/CD integration, use JSON output: 
flowdeck test --json
Example JSON output: 
{"type":"test_started","test":"LoginTests/testValidLogin"}
{"type":"test_passed","test":"LoginTests/testValidLogin","duration":0.123}
{"type":"test_started","test":"LoginTests/testInvalidPassword"}
{"type":"test_failed","test":"LoginTests/testInvalidPassword","message":"Expected failure but got success"}
{"type":"test_summary","passed":1,"failed":1,"skipped":0,"duration":0.456}

​
CI/CD Integration

​
GitHub Actions Example

name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4

      - name: Install FlowDeck
        run: curl -sSL https://flowdeck.studio/install.sh | sh

      - name: Run Tests
        env:
          FLOWDECK_LICENSE_KEY: ${{ secrets.FLOWDECK_LICENSE_KEY }}
        run: |
          flowdeck test \
            --workspace MyApp.xcworkspace \
            --simulator "iPhone 16" \
            --json > test-results.json

      - name: Upload Results
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: test-results.json

​
Parsing Results

# Count passed tests
flowdeck test --json | \
  jq -s '[.[] | select(.type == "test_passed")] | length'

# List failed tests
flowdeck test --json | \
  jq -s '[.[] | select(.type == "test_failed")] | .[].test'

​
Test Output

​
Human-Readable Output

🧪 Running tests...
  Workspace: MyApp.xcworkspace
  Scheme: MyApp
  Configuration: Debug
  Simulator: iPhone 16 Pro

Test Results
============

Total Tests: 45
Passed: 43 ✅
Failed: 2 ❌
Skipped: 0 ⏭️
Duration: 12.34s

Failures:
  ❌ testLoginWithInvalidCredentials: Expected failure but got success
  ❌ testNetworkTimeout: Async expectation not fulfilled

❌ Some tests failed.

​
Tips

Use --json output in CI/CD for reliable parsing and integration with test reporting tools.
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.

​
Troubleshooting

​
Tests Not Discovered

Test discovery parses source files directly. If tests aren’t found:
  1. Ensure test files are in the scheme’s test targets
  2. Verify test classes inherit from XCTestCase or use @Test/@Suite
  3. Check that XCTest methods start with test
# Verify scheme and targets
flowdeck context --json | jq '.schemes'
flowdeck test discover --filter "YourTestClass"

​
Simulator Issues

If tests fail to start, try booting the simulator first: 
flowdeck simulator list --platform iOS
flowdeck simulator boot <UDID>
flowdeck test -S "iPhone 16"