Platform Issues

Platform-specific troubleshooting for Windows, macOS, and Linux

Platform Issues

This guide covers platform-specific issues and solutions for Windows, macOS, and Linux.

macOS

Gatekeeper Blocks Application

Symptom:

"tkit" cannot be opened because the developer cannot be verified.

Solution 1: System Preferences

  1. Open System Preferences → Security & Privacy
  2. Click General tab
  3. You'll see "tkit was blocked from use"
  4. Click Allow Anyway
  5. Run the command again, click Open when prompted

Solution 2: Terminal Command

# Remove quarantine attribute
xattr -d com.apple.quarantine ./tkit

# Verify
xattr ./tkit
# Should show no output or no quarantine attribute

Solution 3: Right-Click Open

  1. In Finder, right-click (or Control-click) on tkit
  2. Select Open
  3. Click Open in the dialog

"Operation not permitted" on macOS Catalina+

Symptom: Terminal operations fail even with proper permissions.

Solution:

  1. Open System Preferences → Security & Privacy → Privacy
  2. Select Full Disk Access
  3. Add Terminal.app (or your terminal emulator)
  4. Restart Terminal

Apple Silicon (M1/M2/M3) Issues

Symptom: Binary doesn't run or crashes immediately.

Solution:

  • Ensure you downloaded the darwin-arm64 version
  • If using Intel version, install Rosetta 2: 
    softwareupdate --install-rosetta

Browser Not Found on macOS

Symptom: "Could not find Chrome installation"

Solution: Chrome/Edge must be installed in standard locations:

  • Chrome: /Applications/Google Chrome.app
  • Edge: /Applications/Microsoft Edge.app

Or specify browser path:

frontend:
  browser: chromium
  executablePath: "/path/to/browser"

Windows

Windows Defender SmartScreen

Symptom:

Windows protected your PC. Windows Defender SmartScreen prevented an unrecognized app from starting.

Solution:

  1. Click More info
  2. Click Run anyway

Or disable for the file:

  1. Right-click tkit.exe
  2. Select Properties
  3. Check Unblock checkbox
  4. Click Apply

Antivirus Blocking Execution

Symptom: Test executable is quarantined or deleted.

Solution: Add exclusion in your antivirus software for:

  • The TestFlowKit executable
  • Your test project directory

For Windows Defender:

  1. Open Windows Security
  2. Go to Virus & threat protection
  3. Under Virus & threat protection settings, click Manage settings
  4. Scroll to Exclusions, click Add or remove exclusions
  5. Add the TestFlowKit directory

Path Too Long Errors

Symptom: "The filename or extension is too long"

Solution:

  1. Enable long paths in Windows: 
    # Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
  2. Move project to shorter path (e.g., C:\tests\)

PowerShell Execution Policy

Symptom: Scripts or commands blocked by execution policy.

Solution:

# Check current policy
Get-ExecutionPolicy

# Set for current user
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Line Ending Issues

Symptom: Feature files fail to parse on Windows.

Solution: Configure Git to handle line endings:

git config --global core.autocrlf input

Or configure your editor to use LF line endings.

Browser GPU Issues

Symptom: Browser crashes or displays incorrectly.

Solution: Disable GPU acceleration:

frontend:
  args:
    - "--disable-gpu"
    - "--disable-software-rasterizer"

Linux

Permission Denied

Symptom: Cannot execute binary.

Solution:

chmod +x ./tkit

Missing Dependencies

Symptom: Binary fails with "shared library not found"

Solution for Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y \
  libnss3 \
  libatk1.0-0 \
  libatk-bridge2.0-0 \
  libdrm2 \
  libxkbcommon0 \
  libxcomposite1 \
  libxdamage1 \
  libxfixes3 \
  libxrandr2 \
  libgbm1 \
  libasound2

Solution for CentOS/RHEL:

sudo yum install -y \
  nss \
  atk \
  at-spi2-atk \
  libdrm \
  libxkbcommon \
  libXcomposite \
  libXdamage \
  libXfixes \
  libXrandr \
  mesa-libgbm \
  alsa-lib

Running in Docker

Symptom: Browser fails to launch in container.

Solution: Use proper base image and security options:

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    chromium-browser \
    libnss3 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libdrm2 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    fonts-liberation \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

# Copy TestFlowKit
COPY tkit /usr/local/bin/
RUN chmod +x /usr/local/bin/tkit

Run with:

docker run --cap-add=SYS_ADMIN your-image tkit run --headless

Or use --no-sandbox:

frontend:
  args:
    - "--no-sandbox"
    - "--disable-setuid-sandbox"

Display Issues (X11)

Symptom: "No display" error when not using headless mode.

Solution 1: Use headless mode

tkit run --headless

Solution 2: Set up virtual display

# Install Xvfb
sudo apt-get install xvfb

# Run with virtual display
xvfb-run tkit run

Solution 3: Export display

export DISPLAY=:0
tkit run

Snap/Flatpak Browser Issues

Symptom: Snap-installed Chrome doesn't work with TestFlowKit.

Solution: Install browser via apt instead of snap:

# Remove snap version
sudo snap remove chromium

# Add Google Chrome repository
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list

# Install
sudo apt-get update
sudo apt-get install google-chrome-stable

CI/CD Environments

GitHub Actions

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y libnss3 libatk1.0-0
      
      - name: Run tests
        run: |
          chmod +x ./tkit
          ./tkit run --headless

GitLab CI

test:
  image: ubuntu:22.04
  before_script:
    - apt-get update && apt-get install -y chromium-browser libnss3
  script:
    - chmod +x ./tkit
    - ./tkit run --headless

Jenkins

pipeline {
    agent {
        docker {
            image 'ubuntu:22.04'
            args '--cap-add=SYS_ADMIN'
        }
    }
    stages {
        stage('Test') {
            steps {
                sh 'chmod +x ./tkit'
                sh './tkit run --headless'
            }
        }
    }
}

Next Steps