TestIntel — Troubleshooting

Installation

testintel command not found

The CLI entry point may not be on your PATH. Either:

• Add the scripts directory to PATH (shown in pip install output)
• Use python -m testintel.cli.main instead

pip install -e . fails with license classifier error

Update setuptools: pip install --upgrade setuptools>=68

AI Provider

"Invalid API key" from Anthropic/OpenAI

• Verify the key is set: echo $env:ANTHROPIC_API_KEY (PowerShell) or echo $ANTHROPIC_API_KEY (bash)
• Keys must be set in the same terminal where TestIntel is running
• For Docker, pass via -e ANTHROPIC_API_KEY=your-key or in docker-compose.yml

AI responses are generic / not using code context

• Check the logs for "Loaded X files from..." — if 0 files, the code context failed
• Verify GITHUB_TOKEN is set for private repos
• For local workspace, verify the path exists and contains source files

"Rate limit exceeded" from AI provider

• Anthropic/OpenAI have per-minute rate limits on their side
• TestIntel's retry logic will wait and retry automatically
• If persistent, check your AI provider's usage dashboard

GitHub Integration

"404 Not Found" when fetching repo

• Use owner/repo format, not the full URL
• The full URL https://github.com/owner/repo is auto-stripped, but verify the repo exists and is accessible
• For private repos, ensure GITHUB_TOKEN has repo scope

No files loaded from repo

• Check if the repo has files on the main branch (some repos use master)
• Set the branch field explicitly if not main

Jira Integration

"410 Gone" from Jira search

• The old GET /rest/api/3/search endpoint is deprecated
• TestIntel uses the new POST /rest/api/3/search/jql endpoint automatically
• Ensure your Jira instance is up to date

Jira connection fails

• Verify JIRA_EMAIL and JIRA_API_TOKEN are set
• Generate a token at https://id.atlassian.com/manage-profile/security/api-tokens
• Verify jira.url in config.yaml is correct (e.g. https://yourorg.atlassian.net)

Xray Integration

Authentication fails

• Xray uses client ID + client secret (not the Jira token)
• Generate at Jira → Apps → Xray → Settings → API Keys
• Set both XRAY_CLIENT_ID and XRAY_CLIENT_SECRET

Push fails with 400 Bad Request

• Run testintel discover to ensure schema mappings are current
• Check that the project key in config.yaml matches your Jira project

Zephyr Scale Integration

"401 Unauthorized"

• Zephyr uses a separate JWT token from Jira
• Generate at https://id.atlassian.com/manage-profile/security/api-tokens
• This is a different token than your Jira API token

Web UI

Tabs not working / page not loading

• Hard refresh with Ctrl+Shift+R to clear cached JS/CSS
• Check browser console (F12) for JavaScript errors
• Verify uvicorn is running and accessible at the URL

API key field visible

• Set TESTINTEL_API_KEY or TESTINTEL_ADMIN_KEY env var before starting — the UI auto-detects and hides the field

Sync buttons not showing

• Sync buttons only appear when Xray/Zephyr credentials are configured
• Check Settings tab → Integrations to verify connection status

Docker

Container exits immediately

• Check logs: docker logs testintel
• Ensure config.yaml is mounted: -v ./config.yaml:/app/config.yaml
• Verify env vars are passed correctly

Data not persisting between restarts

• Mount the data volume: -v ./testintel_data:/app/testintel_data

Performance

Chat responses are slow

• AI response time depends on the provider and context size
• Reduce context by using selective file loading (already built in)
• Use a faster model (e.g. claude-sonnet-4-20250514 instead of opus)

High token usage

• Session context caching reduces repeat file loading
• Selective KB and file loading sends only relevant content
• Clear chat session when switching topics to avoid accumulating context

Schema Discovery

testintel discover shows "not configured"

• Ensure integration env vars are set in the same terminal
• Only configured integrations are scanned — unconfigured ones are skipped

Network / VPN / Firewall

Required outbound domains

TestIntel needs HTTPS (port 443) access to these external services:

VPN compatibility

TestIntel works with all VPN configurations:

• Split tunnel VPN: No issues — external API calls go direct
• Full tunnel VPN: Works, but corporate firewall must allow the domains above
• Corporate proxy: Set HTTP_PROXY / HTTPS_PROXY environment variables if required

Connection errors behind a firewall

If you see connection timeouts or SSL errors:

1. Check if the required domains are whitelisted in your firewall

1. Check if a proxy is required: $env:HTTPS_PROXY="http://proxy.company.com:8080"

1. TestIntel's retry logic will attempt each request twice before failing

HTTPS for production

When deploying TestIntel for team access (not localhost), use HTTPS:

• Place behind a reverse proxy (nginx, Caddy, Traefik) with TLS
• Or use a cloud load balancer with SSL termination
• The Web UI shows a warning banner if accessed over HTTP on a non-localhost address

Getting Help

• GitHub Issues: https://github.com/octoblue-tech/testintel/issues
• Documentation: https://github.com/octoblue-tech/testintel#readme
• API Docs: http://localhost:8000/docs (when running)

Data Safety & Backups

Automatic Backups

TestIntel automatically creates a .backup.json file before every inventory and history save. If data is corrupted, you can recover by:

1. Stop TestIntel

1. Copy inventory.backup.json → inventory.json (in the project's data folder)

1. Restart TestIntel

Destructive Operations

All delete operations require a ?confirm=true parameter:

• DELETE /projects/{name}?confirm=true — removes project config only, data files are preserved
• DELETE /knowledge/{key}?confirm=true — deletes a KB document
• Archive (not delete) is the default for test cases — archived tests remain in the data

S3 Storage — Enable Versioning

If using S3 storage, enable bucket versioning for automatic rollback:

aws s3api put-bucket-versioning --bucket your-testintel-bucket --versioning-configuration Status=Enabled

This gives you automatic version history on every file. To recover a previous version:

aws s3api list-object-versions --bucket your-testintel-bucket --prefix path/to/inventory.json
aws s3api get-object --bucket your-testintel-bucket --key path/to/inventory.json --version-id VERSION_ID recovered.json

Local Storage — Backup Recommendations

For local storage deployments:

• Docker: mount testintel_data/ as a volume on a backed-up filesystem
• Direct install: add testintel_data/ to your regular backup schedule
• Manual backup: cp -r testintel_data/ testintel_data_backup_$(date +%Y%m%d)/

Concurrent Access

TestIntel uses file-based storage with automatic backups. For teams under ~10 concurrent users, this is reliable. For larger teams, consider:

• Using S3 storage (better concurrency handling)
• Future: database backend (SQLite/Postgres) for full ACID compliance