qtrl
Sign In

Jira Forge App

Generate AI-powered test cases from Jira issues without leaving Jira.

Overview

The qtrl Forge app adds a test generation panel to every Jira issue. Your team can click a button to turn any issue into a test case in qtrl, using the issue's summary, description, and acceptance criteria as input. The generated test appears in your qtrl project and a direct link shows up in the Jira issue panel.

This is separate from the Jira OAuth integration in qtrl's organization settings, which pulls Jira data into qtrl. The Forge app works the other way: it pushes from Jira to qtrl.

Setup for Jira admins

Before your team can generate tests, a Jira administrator needs to complete two configuration steps: connecting your qtrl account and mapping each Jira project to a qtrl project.

Step 1: Connect your qtrl account

This is a one-time setup that applies to your entire Jira site.

  1. In Jira, go to Settings (gear icon) and open Apps.
  2. Find qtrl Configuration in the list and click Configure.
  3. Enter your qtrl API key. You can generate one from your qtrl organization settings page. Make sure the key has "write" scope.
  4. Click Save Connection. The app will verify the key works before saving.

If you need to rotate the API key later, come back to this page and enter a new key. The old key will be replaced.

Step 2: Map Jira projects to qtrl projects

Each Jira project needs to be mapped to a specific qtrl project. This tells the app where to create test cases when someone generates a test from an issue in that project.

  1. Open the Jira project you want to configure.
  2. Go to Project Settings (bottom of the left sidebar).
  3. Click Apps, then select qtrl Configuration.
  4. Select the qtrl project from the dropdown. The app fetches your available projects from qtrl automatically.
  5. Choose a test folder where generated tests will be placed. You can pick an existing folder or create a new one (it will be created automatically when the first test is generated).
  6. Under After generating, choose whether to create the test case only or also run it automatically. Most teams start with "Create test case only" so they can review tests before running them.
  7. Click Save Mapping.

Repeat this for each Jira project your team uses. Each Jira project maps to exactly one qtrl project.

Generating a test case from an issue

Once the admin setup is done, any team member can generate tests from Jira issues.

  1. Open any Jira issue in the configured project.
  2. Scroll down to the qtrl Test Generator panel on the issue page.
  3. Click Generate Test Case.
  4. The button disables and a spinner appears while the AI generates the test. This typically takes 30 seconds to a couple of minutes depending on the complexity of the issue.
  5. When generation finishes, a link to the test case appears in the panel. Click it to open the test directly in qtrl.

What the AI uses to generate the test

The app sends three fields from the Jira issue to qtrl:

  • Summary: the issue title
  • Description: the full issue description
  • Acceptance criteria: the acceptance criteria custom field, if present

The more detail you include in these fields, the better the generated test will be. Write acceptance criteria as specific, testable statements for the best results. For general tips on writing good input for AI test generation, see Best Practices: Creating Tasks.

Viewing and managing linked tests

After a test has been generated for an issue, the qtrl panel remembers the link. When you or anyone else opens that issue later, the panel shows the linked test case with a clickable link to qtrl.

Execution history

If the linked test has been executed (either manually in qtrl or as part of a test run), the panel shows recent execution results with their status and duration. Click "View all in qtrl" to see the full execution history.

Regenerating a test

If the requirements have changed or you want a fresh test, click the "Regenerate test case" link below the test. This clears the existing link and immediately starts a new generation. The previous test still exists in qtrl but is no longer linked to the Jira issue.

Permissions and security

The Forge app has minimal permissions. It can only read Jira issue fields (summary, description, acceptance criteria) and store configuration data in Atlassian's encrypted storage. It cannot modify Jira issues or access other Jira data.

Your qtrl API key is stored securely in Forge's encrypted key-value storage and is never exposed to end users. Only Jira site administrators can view or change the global configuration.

Troubleshooting

"qtrl is not configured"

The global API connection has not been set up. Ask a Jira admin to go to Jira Settings > Apps > qtrl Configuration and enter the API key.

"qtrl is not configured for this Jira project"

This Jira project hasn't been mapped to a qtrl project yet. A project admin needs to go to Project Settings > Apps > qtrl Configuration and set up the mapping.

Generation is taking longer than expected

The panel polls for up to two minutes. If the test hasn't finished by then, the spinner stops and a message appears. The generation may still be running in qtrl. Refresh the Jira issue page to check again, or open qtrl to see the task status directly.

Generation failed

If generation fails, the panel shows an error message and a "Try Again" button. Common causes include an invalid or expired API key, the qtrl project being deleted, or a temporary API outage. If the problem persists, check the API key in the admin configuration.