Common Issues
| Problem | Fix |
|---|
| macOS "unidentified developer" | System Preferences → Security → Allow Anyway, or xattr -d com.apple.quarantine ./tkit |
| Linux permission denied | chmod +x ./tkit |
| Windows SmartScreen block | Click More info → Run anyway |
| Problem | Fix |
|---|
| Config not found | Run from project root, or tkit run --config path/to/testflowkit.yml |
| Invalid YAML | Check indentation (spaces only), quote strings with special chars |
| Element not in config | Add to frontend.elements — names are case-sensitive |
Undefined {{ env.* }} | Define in env: block or env file; run tkit validate |
- Test selector in DevTools:
document.querySelector('#selector') - Add fallback selectors (most reliable first)
- Increase
frontend.default_timeout - Scroll into view first:
the user scrolls to the "element" element
frontend:
elements:
login:
submit_button:
- "[data-testid='submit']"
- "#submit-btn"
- "button[type='submit']"
- Ensure Chrome/Edge is installed
- Try headless:
tkit run --headless - Playwright: run
tkit install after setting driver: "playwright"
| Problem | Fix |
|---|
| Connection refused | Check server is running and base_url is correct |
| 401 Unauthorized | Set auth header or configure security_schemes |
| Timeout | Increase apis.default_timeout or endpoint timeout |
| Wrong endpoint | Verify "api_name.endpoint_name" matches config keys |
And I set the header "Authorization" to "Bearer {{auth_token}}"
| Problem | Fix |
|---|
| Variable not substituted | Store before use; check spelling |
| Empty value | Verify the storing step ran successfully |
| Not available across scenarios | Use global hooks |
tkit run --debug # Full request/response payloads
tkit validate # Check config and env references
Enable screenshots on failure:
frontend:
screenshot_on_failure: true
Open a GitHub issue with version (tkit version), OS, minimal reproduction, and error output.