Core Concepts
A quick reference for the key terms and ideas you'll encounter throughout the RoostGPT docs.
How It All Fits Together
Roost Token
A string that authenticates your account with the RoostGPT service. Used in the Web UI (automatically after sign-in), in the CLI via ROOST_TOKEN, and in the VS Code extension settings.
Tokens are tied to a Roost Domain (app.roost.ai for cloud, or your self-hosted hostname). If the domain doesn't match the token, authentication fails.
Connector
A Connector is a centrally stored, reusable credential that RoostGPT uses to connect to an external service. Instead of entering credentials every time you configure a test suite, you define a connector once and reference it across any number of test suites.
This central store has two practical benefits:
- Reuse — the same Git token, AI key, or Jira credential can be shared across all test suites without re-entry.
- Single point of update — when a credential rotates or expires, you update it in one connector and every test suite using it picks up the change automatically.
RoostGPT supports the following connector types:
| Type | Connects to | Used for |
|---|---|---|
| AI Connector | OpenAI, Anthropic Claude, Azure OpenAI, Google Gemini, AWS Bedrock | Calling the AI model during test generation |
| Git Connector | GitHub, GitLab, Bitbucket, Azure Repos (cloud or self-hosted) | Cloning source code and opening Pull Requests with generated tests |
| Ticketing Connector | Jira, Azure DevOps, and other issue trackers | Fetching user stories as input for Functional and Integration test generation |
| Notification Connector | Slack, Microsoft Teams, and other messaging platforms | Sending test generation notifications and results to your team's channel |
Connectors are managed via Connectors in the top navigation bar of the Web UI. In the CLI, equivalent credentials are set as environment variables in the .env file.
Test Plan
A test plan is a saved configuration for a test generation job. It records:
- The source repository, branch, and language
- The AI provider and model
- The test type and framework
- Any business requirement inputs (Jira ticket, user input file)
You can re-trigger, improve, or share a test plan without re-entering all the details each time.
Source vs. Destination Repository
By default, RoostGPT pushes generated tests back to the same repository it read the source code from (SAME_TARGET_DETAIL=true).
If you want tests to go to a different repository — for example, a dedicated test repo — set SAME_TARGET_DETAIL=false and provide DESTINATION_* credentials separately.
Test Types
RoostGPT generates five distinct test types, each from a different input:
| Type | Input | Output |
|---|---|---|
| Unit | Source code files | Runnable test files per class/module |
| API | Swagger / OpenAPI / Postman spec | Postman collection, Karate, Rest Assured |
| Integration | API spec + Gherkin template | End-to-end suite with CSV test data |
| Functional | Jira / Azure DevOps user story | Gherkin .feature file + API spec |
| UI | Application URLs, natural language requirements, Word/PDF/Excel | Playwright test suites with POM architecture, Gherkin output, PDF reports |
See Test Generation for the full framework matrix per type.
Interfaces
RoostGPT can be used through four interfaces — all produce the same test output:
| Interface | Best for |
|---|---|
| Web UI | Teams, centralized management, webhook-driven automation |
| CLI | Terminal workflows, CI/CD pipelines, local generation |
| IDE Plugin | Individual developers generating tests file-by-file in VS Code |
| API | Programmatic integration from CI/CD tools |
See Choose Your Interface for a full feature comparison.
Webhook
A URL that your Git platform (GitHub, GitLab, etc.) calls when a push or Pull Request event occurs. RoostGPT listens on this URL and automatically triggers test generation in response — no manual action required.
Webhooks are configured on your Git platform (GitHub, GitLab, Bitbucket, or Azure DevOps) by pointing the webhook payload URL to your RoostGPT server. Azure DevOps uses Service Hooks instead. See Webhooks for setup steps per platform.
Docker Mode
When enabled (--docker flag in CLI, UseDocker=true in VS Code), RoostGPT runs test compilation and execution inside an isolated Docker container rather than your local environment. This avoids dependency conflicts and ensures a clean execution environment.
Docker mode requires Docker Engine to be running locally. Language version variables (JAVA_VERSION, GO_VERSION, etc.) only apply in Docker mode.
ROOST_DIR
The working directory used by RoostGPT to store temporary files, logs, binaries, and generated output during a run. Defaults to /var/tmp/Roost/RoostGPT. Configurable via the ROOST_DIR variable in the CLI .env file.
On self-hosted deployments, this path corresponds to the dedicated volume mounted at /var/tmp/Roost.
Iterations
When VERIFY_TEST=true, RoostGPT runs the generated tests after generation. If they fail, it feeds the error back to the AI model and regenerates — up to ITERATION times. This self-healing loop improves the chance that tests compile and pass without manual intervention.
Hosted Type
Controls whether RoostGPT connects to a cloud or self-hosted Git instance:
HOSTED_TYPE=cloud— connects togithub.com,gitlab.com,bitbucket.org, ordev.azure.comHOSTED_TYPE=hosted— connects to a self-hosted instance at the URL specified inGIT_HOSTED_URL