Skip to main content

TestPlanIt for Jira

The TestPlanIt for Jira app is an Atlassian Forge app that displays test cases, test runs, and exploratory testing sessions directly in Jira issue panels.

Features​

  • Issue Panel — View linked test cases, test runs, and sessions on every Jira issue
  • Settings Page — Admin configuration for your TestPlanIt instance URL and API key
  • Secure Authentication — API key authentication with timing-safe validation

Test Runs & Sessions​

Test runs and sessions panel

Test Cases​

Test cases panel

Requirements​

  • Jira Cloud (Software)
  • A TestPlanIt instance hosted on a *.testplanit.com subdomain
Domain Restriction

The Marketplace version of this app only works with *.testplanit.com subdomains (e.g., https://demo.testplanit.com). This is an Atlassian Forge security requirement — apps must explicitly whitelist external domains in the manifest.

If you self-host TestPlanIt on a custom domain, see Custom Domain Setup below.

Installation​

From the Atlassian Marketplace​

  1. Search for "TestPlanIt for Jira" on the Atlassian Marketplace
  2. Click Install and select your Jira instance

Manual Installation (Development)​

cd forge-app
npx forge install

Select your Jira instance when prompted.

Configuration​

Step 1: Generate a Forge API Key in TestPlanIt​

  1. Log into your TestPlanIt instance as an admin
  2. Go to Admin > Integrations
  3. Find or create a Jira integration
  4. Click Generate Forge API Key
  5. Copy the generated key

Step 2: Configure the App in Jira​

  1. In Jira, go to Settings (gear icon) > Apps > TestPlanIt Settings
  2. Enter your TestPlanIt Instance URL (e.g., https://yourcompany.testplanit.com)
  3. Enter the Forge API Key from Step 1
  4. Click Test Connection to verify connectivity
  5. Click Save Configuration

TestPlanIt settings page

Step 3: Verify​

Navigate to any Jira issue that has linked test cases in TestPlanIt. The TestPlanIt panel will appear on the right side showing:

  • Test Cases — Linked test cases with status
  • Test Runs — Recent test runs referencing this issue
  • Sessions — Exploratory testing sessions linked to this issue

Click any item to open it directly in TestPlanIt.

Linking Tests to Jira Issues​

Tests are linked by associating Jira issue keys in TestPlanIt:

  1. In TestPlanIt, navigate to a test case, test run, or session
  2. Link it to a Jira issue using the issue key (e.g., PROJ-123)
  3. The linked test will automatically appear in the Jira issue panel

Troubleshooting​

"Not Configured" Message​

The app hasn't been configured yet. Go to Jira Settings > Apps > TestPlanIt Settings and enter your instance URL and API key.

Connection Test Fails​

  • Verify the URL is correct and uses https://
  • Ensure the URL is a *.testplanit.com subdomain
  • Check that your TestPlanIt instance is accessible
  • Make sure there's no trailing slash in the URL

401 Unauthorized Error​

  • Verify the Forge API Key is correct
  • Regenerate the key in TestPlanIt if needed: Admin > Integrations > Jira > Forge API Key
  • Make sure you're using the Forge API Key, not a regular API token

Panel Shows "No Tests Linked"​

  • Confirm that test cases are linked to this Jira issue in TestPlanIt
  • Check that the Jira issue key matches exactly (e.g., PROJ-123)

Check Forge Logs​

For deeper debugging, use the Forge CLI:

cd forge-app
npx forge logs

Custom Domain Setup​

If your TestPlanIt instance runs on a custom domain (not *.testplanit.com), you cannot use the Marketplace version. Instead, deploy your own Forge app:

  1. Clone the TestPlanIt repository
  2. Edit forge-app/manifest.yml — replace the domain whitelist with your domain: 
    permissions:
      external:
        fetch:
          backend:
            - 'your-domain.com'
            - '*.your-domain.com'
          client:
            - 'your-domain.com'
            - '*.your-domain.com'
        images:
          - 'your-domain.com'
          - '*.your-domain.com'
  3. Create a new Forge app at the Atlassian Developer Console
  4. Update the app.id in manifest.yml with your new app ID
  5. Build and deploy: 
    cd forge-app
    npm install
    npm run build
    npx forge deploy
    npx forge install

See CUSTOM_DOMAIN_SETUP.md for the full guide.

Technical Details​

  • Platform: Atlassian Forge (Custom UI)
  • Runtime: Node.js 20.x
  • Frontend: React 18 with Tailwind CSS
  • Backend: Forge Resolver functions
  • Storage: Forge Storage API (per-installation key-value store)

API Endpoints Used​

The app calls these endpoints on your TestPlanIt instance:

EndpointPurpose
GET /version.jsonConnection test (returns app version)
GET /api/integrations/jira/test-infoFetch linked test cases, runs, and sessions

The test-info endpoint requires the X-Forge-Api-Key header for authentication.