langflow/.github/workflows/cross-platform-test.md

Cross-Platform Install Tests

Unified workflow for testing langflow installation across multiple platforms, supporting both manual and programmatic execution.

Manual Testing

1. Test from PyPI

Tests published langflow packages from PyPI across all platforms.

Via GitHub UI:

1. Go to Actions → Cross-Platform Installation Test
2. Check "Test from PyPI instead of building from source"
3. Optionally specify a version (leave empty for latest)
4. Click "Run workflow"

Via CLI:

# Test latest version
gh workflow run cross-platform-test.yml -f test-from-pypi=true

# Test specific version
gh workflow run cross-platform-test.yml \
  -f test-from-pypi=true \
  -f langflow-version="1.0.18"

2. Test from Source

Builds and tests langflow from current branch source code using release-like dependency resolution (transforms workspace dependencies to published packages for testing parity).

Via GitHub UI:

1. Go to Actions → Cross-Platform Installation Test
2. Leave "Test from PyPI instead of building from source" unchecked
3. Click "Run workflow"

Via CLI:

# Test current branch with release-like dependencies
gh workflow run cross-platform-test.yml -f test-from-pypi=false

Programmatic Testing

For CI, releases, and other automated workflows that test wheel installation:

jobs:
  test-cross-platform:
    uses: ./.github/workflows/cross-platform-test.yml
    with:
      base-artifact-name: "dist-base"
      main-artifact-name: "dist-main"
      test-timeout: 120  # optional, defaults to 5

Platforms Tested

• Linux: AMD64
• macOS: Intel (AMD64), Apple Silicon (ARM64)
• Windows: AMD64
• Python versions:
  • All platforms: 3.10, 3.12, 3.13, and 3.14
  • Stability: 3.10, 3.12, and 3.13 are required to pass (blocking)
  • Preview: 3.14 testing is optional (non-blocking) to monitor ecosystem readiness
  • Note: macOS Intel (x86_64) is tested only on Python 3.12. macOS x86_64 is being dropped across the ecosystem — PyTorch ships no x86_64 wheels for py>=3.13 and onnxruntime shipped none after 1.23 — and langflow requires onnxruntime>=1.26 on py>=3.14, so macOS Intel + py>=3.14 cannot resolve. The 3.13 (blocking) and 3.14 (preview) sets therefore run on Linux, Windows, and macOS arm64 only

What Gets Tested

1. Package Installation: uv pip install langflow (PyPI) or local wheel installation
2. Dependencies: Additional packages like openai for full functionality
3. CLI Help: langflow --help
4. Server Startup: langflow run --backend-only with /health_check endpoint validation
5. Python Import: import langflow

Common Options

# Extended timeout (10 minutes instead of default 5)
gh workflow run cross-platform-test.yml \
  -f test-timeout=10

# Test specific PyPI version
gh workflow run cross-platform-test.yml \
  -f test-from-pypi=true \
  -f langflow-version="1.0.18"

Use Cases

• Before releases: Verify current branch works on all platforms
• After PyPI publish: Confirm published packages install correctly
• Debugging issues: Test specific versions when users report problems
• Development: Quick cross-platform validation during feature work

Technical Details

Installation Methods

• PyPI testing: Uses uv pip install with official PyPI packages
• Source testing: Transforms workspace dependencies to published packages (like nightly builds), then builds wheels from source and installs locally
• Dependencies: Automatically installs additional packages (openai) for full functionality

Health Checking

• Endpoint: Uses /health_check for reliable server readiness validation
• Validation: Checks database connectivity and chat service functionality
• Timeout: Configurable timeout with proper cross-platform handling

Platform-Specific Optimizations

• Stable versions: Python 3.10, 3.12, and 3.13 provide reliable package ecosystem support
• Preview testing: Python 3.14 runs as non-blocking to monitor when it becomes viable
• Virtual Environments: Uses uv venv --seed for consistent pip availability

Workflow Architecture

Unified Single-File Design:

cross-platform-test.yml
├── workflow_dispatch (Manual UI)
│   ├── PyPI Testing (test-from-pypi=true)
│   └── Source Testing (test-from-pypi=false)
└── workflow_call (Programmatic API)
    └── Wheel Testing (always uses wheel method)

Key Benefits:

• Single File: No complex workflow chains or parameter passing issues
• Unified Logic: Same test matrix for all use cases
• Smart Routing: Automatically determines install method based on trigger type
• Context-Aware: Summary messages adapt to manual vs programmatic usage

Trigger Types

Manual (workflow_dispatch):

• Simple boolean toggle: "Test from PyPI" vs "Test from Source"
• Source testing always uses release-like dependency resolution for testing parity
• User-friendly parameter names
• Context-specific success/failure messages

Programmatic (workflow_call):

• Full parameter control for CI/releases
• Backward compatible with existing workflows
• Always uses wheel installation method (tests built artifacts)

Implementation Details

The workflow uses dynamic job conditions to route execution:

# Build only runs for source testing or when no artifacts provided
build-if-needed:
  if: |
    (github.event_name == 'workflow_dispatch' && inputs.test-from-pypi == false) ||
    (github.event_name == 'workflow_call' && (inputs.base-artifact-name == '' || inputs.main-artifact-name == ''))

# Test matrix adapts install method based on trigger
test-installation:
  steps:
    - name: Determine install method
      # workflow_dispatch: maps boolean to install method
      # workflow_call: always uses wheel method
    - name: Install from PyPI
      if: steps.install-method.outputs.method == 'pypi'
    - name: Install from wheels
      if: steps.install-method.outputs.method == 'wheel'

Known Issues

macOS Compilation Issues (Historical)

Issue: Previously, nightly/release builds could fail on macOS with Python 3.13 due to chroma-hnswlib compilation errors:

clang: error: unsupported argument 'native' to option '-march='
error: command '/usr/bin/clang++' failed with exit code 1

Root Cause: Systematic difference in dependency resolution between workspace builds vs published packages:

Build Type	Package Source	Dependencies	chromadb	Result
Manual/Source	Workspace (langflow-base = { workspace = true })	162 packages	❌ Not included	✅ Success
Nightly/Release	Published (langflow-base-nightly==0.5.0.dev21)	420 packages	✅ Included	❌ Compilation fails

Technical Details:

1. Workspace builds use local src/backend/base/pyproject.toml which excludes chromadb
2. Nightly builds modify dependencies via scripts/ci/update_uv_dependency.py:
   • Changes: langflow-base~=0.5.0 → langflow-base-nightly==0.5.0.dev21
   • Uses published PyPI package with full dependency tree including chromadb==0.5.23
3. macOS clang doesn't support -march=native flag used by chroma-hnswlib compilation

Current Status:

• Stable testing: Python 3.10, 3.12, and 3.13 are required to pass (blocking jobs)
• Preview testing: Python 3.14 runs as non-blocking to monitor ecosystem readiness
• Compilation issues: the historical chroma-hnswlib failure is avoided on the tested install paths (workspace/source builds exclude chromadb); a similar upstream issue surfacing on the preview (3.14) tier stays non-blocking
• Manual testing: Source builds now use the same dependency transformation as nightly builds for testing parity

Files Involved:

• scripts/ci/update_uv_dependency.py - Modifies dependency resolution
• scripts/ci/update_pyproject_combined.py - Orchestrates nightly build changes
• pyproject.toml vs src/backend/base/pyproject.toml - Different dependency trees

Results

• ✅ Success: All platforms pass installation and basic functionality
• ❌ Failure: One or more platforms fail (check logs for details)
• Each platform/Python combination runs independently
• Parallel execution: All platforms tested simultaneously for faster feedback