Common Issues

This guide covers common issues you may encounter when using TestFlowKit and their solutions.

Installation Issues

macOS: "App can't be opened because it is from an unidentified developer"

Symptom: macOS blocks TestFlowKit from running.

Solution:

1. Open System Preferences → Security & Privacy
2. Click General tab
3. Click Allow Anyway next to the TestFlowKit message
4. Try running again and click Open when prompted

Or via terminal:

xattr -d com.apple.quarantine ./tkit

Linux: Permission denied

Symptom: Cannot execute the binary.

Solution:

chmod +x ./tkit

Windows: Windows Defender blocks execution

Symptom: Windows shows a security warning.

Solution:

1. Click More info
2. Click Run anyway

Or add an exclusion in Windows Defender settings.

Configuration Issues

"Configuration file not found"

Symptom: TestFlowKit can't find config.yml.

Solutions:

• Ensure you're running from the correct directory
• Specify config path explicitly:

  tkit run --config path/to/config.yml
  

• Verify file name is exactly config.yml (not config.yaml)

"Invalid YAML syntax"

Symptom: Configuration file fails to parse.

Solutions:

• Check for indentation errors (use spaces, not tabs)
• Validate YAML syntax online (e.g., yamllint.com)
• Ensure quotes are balanced
• Check for special characters that need escaping

# Bad: Missing quotes for special characters
baseUrl: https://example.com?param=value

# Good: Quoted string
baseUrl: "https://example.com?param=value"

"Element not found in configuration"

Symptom: Step refers to undefined element.

Solutions:

• Verify element name matches exactly (case-sensitive)
• Add element to configuration:

  frontend:
    elements:
      my_element: "#my-element"
  

• Check for typos in feature file

Element Detection Issues

"Element not found"

Symptom: TestFlowKit can't locate an element on the page.

Solutions:

1. Verify selector in browser DevTools:

   document.querySelector('#my-selector')
   

2. Check if element is in iframe:

   When the user switches to the "iframe_name" iframe
   And the user clicks the "element" button
   

3. Wait for element to appear:

   When the user waits for the "element" to be visible
   And the user clicks the "element" button
   

4. Add multiple fallback selectors:

   elements:
     submit_btn:
       - "#submit"
       - "[data-testid='submit']"
       - "button[type='submit']"
   

5. Increase timeout:

   frontend:
     timeout: 60000  # 60 seconds
   

"Element is not clickable"

Symptom: Element exists but click fails.

Solutions:

1. Scroll element into view:

   When the user scrolls to the "element" element
   And the user clicks the "element" button
   

2. Wait for overlay to disappear:

   When the user waits for the "loading_overlay" to disappear
   And the user clicks the "element" button
   

3. Use slower motion:

   tkit run --slow-motion 200
   

"Stale element reference"

Symptom: Element reference becomes invalid during test.

Solutions:

• Add a wait after page changes
• Re-query the element after navigation
• Avoid storing element references across page loads

Browser Issues

"Browser failed to launch"

Symptom: Browser doesn't start.

Solutions:

1. Check browser installation:
   • Ensure Chrome/Edge is installed
   • Update to latest browser version
2. Try different browser:

   frontend:
     browser: firefox
   

3. Run in headless mode:

   tkit run --headless
   

4. Check system resources:
   • Close other applications
   • Increase available RAM

"Connection refused" in headless mode

Symptom: Browser starts but can't connect.

Solutions:

• Try non-headless mode to debug
• Check if port is available
• Restart your machine

API Testing Issues

"Connection refused"

Symptom: API requests fail to connect.

Solutions:

• Verify API server is running
• Check baseUrl in configuration
• Ensure correct port number
• Check firewall settings

"401 Unauthorized"

Symptom: API returns authentication error.

Solutions:

1. Verify token is set:

   And I set the request header "Authorization" to "Bearer {{token}}"
   

2. Check token hasn't expired:
   • Refresh token in BeforeAll hook
   • Use shorter test sessions
3. Verify token format:

   # Debug: Print token value
   Then the response should contain "{{auth_token}}"
   

"Timeout waiting for response"

Symptom: API calls time out.

Solutions:

• Increase timeout:

  backend:
    timeout: 30000
  

• Check API server performance
• Verify endpoint path is correct

Test Execution Issues

Tests are too slow

Solutions:

1. Run in headless mode:

   tkit run --headless
   

2. Reduce slow motion:

   frontend:
     slowMotion: 0
   

3. Use parallel execution:

   tkit run --parallel 4
   

4. Optimize waits:

   # Bad: Fixed wait
   When the user waits for 5 seconds
   
   # Good: Wait for condition
   When the user waits for the "element" to be visible
   

Tests pass locally but fail in CI

Solutions:

1. Use headless mode in CI:

   tkit run --headless
   

2. Add explicit waits:

   When the user waits for the "page_loaded" to be visible
   

3. Increase timeouts for CI:

   frontend:
     timeout: 60000
   

4. Check viewport size:

   frontend:
     viewport:
       width: 1920
       height: 1080
   

"Variable not found"

Symptom: Variable substitution fails.

Solutions:

• Verify variable was stored before use
• Check spelling matches exactly
• Ensure variable scope (scenario vs global)
• Verify BeforeAll hook succeeded

Getting Help

If you can't resolve an issue:

1. Check verbose output:

   tkit run --verbose
   

2. Enable screenshots:

   reports:
     screenshotOnFailure: true
   

3. Search GitHub Issues:TestFlowKit Issues
4. Open a new issue with:
   • TestFlowKit version
   • Operating system
   • Minimal reproduction steps
   • Error messages and logs

Next Steps

• Platform Issues — OS-specific problems
• CLI Reference — Command options
• Configuration — Configuration reference