ScriptRunner Connect Managed API for Zephyr Scale

Managed API for Zephyr Scale Cloud is an API Client for Zephyr Scale Cloud by Adaptavist. You can read more about Managed APIs here.

This is ScriptRunner Connect runtime specific version of the Managed API. This package is specifically designed for ScriptRunner Connect's custom runtime and will NOT work in standard Node.js projects. It uses web standards-based APIs (fetch, etc.) and ES modules, making it compatible with ScriptRunner Connect's runtime environment.

Installation

npm install @rbaileysr/zephyr-managed-api

Important: After installing via NPM, you must also add the package through ScriptRunner Connect's Package Manager in the web UI. The package will then be available in your workspace.

Constructing Managed API

In ScriptRunner Connect a Managed API is constructed for you, but if you need to construct it manually, here's how you can do it:

Using API Connection (recommended for ScriptRunner Connect):

import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
import ZephyrApiConnection from '../api/zephyr';

// Base URL is configured in the Generic Connector
const api = createZephyrApi(ZephyrApiConnection);

// With verbose logging enabled (logs full request/response details on API failures)
const apiVerbose = createZephyrApi(ZephyrApiConnection, true);

Using OAuth Token:

import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';

// US region
const api = createZephyrApi(
'your-oauth-token',
'https://api.zephyrscale.smartbear.com/v2'
);

// EU region with verbose logging
const apiEU = createZephyrApi(
'your-oauth-token',
'https://eu.api.zephyrscale.smartbear.com/v2',
true  // Enable verbose logging
);

Verbose Logging

When enabled, verbose logging automatically logs full request and response details whenever an API call fails. This is useful for debugging issues in production environments.

Features:

• Logs full request details (method, path, headers, body)
• Logs full response details (status, headers, body)
• Automatically sanitizes sensitive headers (authorization, API keys)
• Only logs on failures (not on successful requests)
• Includes descriptive messages about what operation was being attempted

Example output when an API call fails:

[Zephyr API Failure]
Operation: GET /testcases/PROJ-T1
Request Details: {
  method: 'GET',
  path: '/testcases/PROJ-T1',
  headers: { 'content-type': 'application/json', authorization: '[REDACTED]' },
  body: null
}
Response Details: {
  status: 404,
  statusText: 'Not Found',
  headers: { 'content-type': 'application/json' },
  body: { message: 'Test case not found' }
}

Supported API calls

• fetch

• Project

  • listProjects
  • getProject

• Status

  • listStatuses
  • getStatus
  • createStatus
  • updateStatus

• Priority

  • listPriorities
  • getPriority
  • createPriority
  • updatePriority

• Environment

  • listEnvironments
  • getEnvironment
  • createEnvironment
  • updateEnvironment

• Folder

  • listFolders
  • getFolder
  • createFolder

• TestCase

  • listTestCases
  • listTestCasesCursorPaginated
  • getTestCase
  • createTestCase
  • updateTestCase
  • getTestCaseLinks
  • createTestCaseIssueLink
  • createTestCaseWebLink
  • listTestCaseVersions
  • getTestCaseVersion
  • getTestCaseTestScript
  • createTestCaseTestScript
  • getTestCaseTestSteps
  • createTestCaseTestSteps

• TestCycle

  • listTestCycles
  • getTestCycle
  • createTestCycle
  • updateTestCycle
  • getTestCycleLinks
  • createTestCycleIssueLink
  • createTestCycleWebLink

• TestPlan

  • listTestPlans
  • getTestPlan
  • createTestPlan
  • createTestPlanIssueLink
  • createTestPlanWebLink
  • createTestPlanTestCycleLink

• TestExecution

  • listTestExecutions
  • listTestExecutionsNextgen
  • getTestExecution
  • createTestExecution
  • updateTestExecution
  • getTestExecutionTestSteps
  • putTestExecutionTestSteps
  • syncTestExecutionScript
  • listTestExecutionLinks
  • createTestExecutionIssueLink

• Link

  • deleteLink

• IssueLink

  • getIssueLinkTestCases
  • getIssueLinkTestCycles
  • getIssueLinkTestPlans
  • getIssueLinkExecutions

• Automation

  • createCustomExecutions
  • createCucumberExecutions
  • createJUnitExecutions
  • retrieveBDDTestCases

• Private ⚠️

  ⚠️ WARNING: Private API Methods

  The following methods use Zephyr's private/unofficial API endpoints that are:

  • Not officially supported by SmartBear
  • Not part of the public API documentation
  • Subject to change at any time without notice
  • Not covered by Standard Support

  Use these methods at your own risk. They may break with future Zephyr updates.

  • Authentication

    • getContextJwt - Get Jira Context JWT token (required for all private API calls)
    • enableZephyrForProject - Enable Zephyr for a Jira project
    • isZephyrEnabledForProject - Check if Zephyr is enabled for a Jira project

  • Comments

    • Test Case: getTestCaseComments, createTestCaseComment, deleteTestCaseComment (v1.4.2+)
    • Test Cycle: getTestCycleComments, createTestCycleComment, deleteTestCycleComment (v1.4.2+)
    • Test Plan: getTestPlanComments, createTestPlanComment, deleteTestPlanComment (v1.4.2+)

  • Config

    • CustomFields: createCustomField, getCustomFields
    • Labels: getLabels, createLabel
    • Iterations: getIterations, createIteration
    • DataSets: getDataSets, createDataSet, updateDataSet
    • archiveConfig - Archive a config item (Environment, Iteration, or Status)
    • unarchiveConfig - Unarchive a config item (Environment, Iteration, or Status)

  • TestCase (entity-based group - v1.4.0+)

    • Archiving: getArchivedTestCases, archiveTestCases, unarchiveTestCases
    • TestScriptData: setTestCaseParamTypeToParameter, setTestCaseParameters, setTestCaseParamTypeToTestData, setTestCaseTestData, getTestCaseTestData, hasTestCaseTestData (all support version parameter in v1.4.2+)
    • Versions: createTestCaseVersion
    • Methods: getTestCaseTestStepsWithIds, createTestCaseTestStepsWithVersion (supports version parameter in v1.4.2+), updateTestCasePlainTextScriptWithVersion (v1.4.2+), updateTestCaseBddScriptWithVersion (v1.4.2+), deleteTestCaseWebLink (v1.4.2+), deleteTestCaseIssueLink (v1.4.2+)

  • TestCycle (entity-based group - v1.4.0+)

    • ExtendedData: getTestCycleIteration, updateTestCycleIteration
    • Methods: deleteTestCycleWebLink (v1.4.2+), deleteTestCycleIssueLink (v1.4.2+)

  • TestExecution (entity-based group - v1.4.0+)

    • ExtendedData: getTestExecutionIteration, updateTestExecutionIteration, getTestExecutionVersion, updateTestExecutionVersion
    • Methods: listAllTestExecutionsForTestCase, createTestExecutionWithTestData, createTestExecutionWithVersion, updateTestExecution, getTestExecutionSteps, updateTestExecutionStepStatus, updateTestExecutionStepComment, getTestCycleItems

  • Versions (deprecated - use Private.TestCase.Versions instead)

    • createTestCaseVersion - Create a new test case version

  • Attachments

    • Test Case: getTestCaseAttachments, downloadAttachment, createTestCaseAttachment, deleteTestCaseAttachment (v1.4.2+)
    • Test Step: getTestStepAttachments, downloadTestStepAttachment, createTestStepAttachment, deleteTestStepAttachment (v1.4.2+)
    • Test Cycle: getTestCycleAttachments, downloadTestCycleAttachment, createTestCycleAttachment, deleteTestCycleAttachment (v1.4.2+)
    • Test Plan: getTestPlanAttachments, downloadTestPlanAttachment, createTestPlanAttachment, deleteTestPlanAttachment (v1.4.2+)
    • Test Execution: getTestExecutionAttachments, downloadTestExecutionAttachment, createTestExecutionAttachment
    • Test Execution Step: getTestExecutionStepAttachments, downloadTestExecutionStepAttachment, createTestExecutionStepAttachment

  • TestPlan (entity-based group - v1.4.2+)

    • Methods: deleteTestPlanWebLink, deleteTestPlanIssueLink

  • VersionControl

    • Test Case (version-specific): getTestCaseIssueLinks, getTestCaseWebLinks, getTestCaseTestScript, getTestCaseTestSteps
    • Test Execution Step: getTestExecutionStepIssueLinks, createTestExecutionStepIssueLink

  • ExtendedData (deprecated - use Private.TestCycle.ExtendedData or Private.TestExecution.ExtendedData instead)

    • Test Cycle: getTestCycleIteration, updateTestCycleIteration
    • Test Execution: getTestExecutionIteration, updateTestExecutionIteration, getTestExecutionVersion, updateTestExecutionVersion

  • TestCaseArchiving (deprecated - use Private.TestCase.Archiving instead)

    • Test Case: getArchivedTestCases, archiveTestCases, unarchiveTestCases

  • TestScriptData (deprecated - use Private.TestCase.TestScriptData instead)

    • Test Case: setTestCaseParamTypeToParameter, setTestCaseParameters, setTestCaseParamTypeToTestData, setTestCaseTestData, getTestCaseTestData, hasTestCaseTestData

  • TestExecutions (deprecated - use Private.TestExecution instead)

    • Test Execution: createTestExecutionWithTestData, createTestExecutionWithVersion, updateTestExecution, getTestExecutionSteps, updateTestExecutionStepStatus, updateTestExecutionStepComment
    • Test Cycle: getTestCycleItems

Private API Authentication

Private API methods require Jira user credentials (email and API token) rather than OAuth tokens. These methods use Jira Basic Authentication to retrieve a Context JWT token, which is then used to authenticate with Zephyr's private endpoints.

Get Context JWT

The Context JWT is a short-lived token (15 minutes) required for all private API calls. See examples.ts for comprehensive usage examples.

Basic Usage:

import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
import ZephyrApiConnection from '../api/zephyr';

const api = createZephyrApi(ZephyrApiConnection);

// Define credentials once
const credentials = {
  userEmail: '[email protected]',
  apiToken: 'jira-api-token',
  jiraInstanceUrl: 'https://your-instance.atlassian.net'
};

// Get Context JWT token
const contextJwt = await api.Private.Authentication.getContextJwt(credentials);

Private API Examples

Comprehensive examples for all private API methods are available in examples.ts. This file includes examples for:

• Authentication: Context JWT, project enablement checks
• Config Operations: Custom fields, labels, iterations, data sets, archiving
• Test Case Operations: Version creation, archiving, test script data management, test steps with version support
• Test Cycle Operations: Extended data (iterations)
• Test Execution Operations: Extended data (iterations, versions), test data handling, version-specific executions, listing all executions
• Attachments: Uploading and managing attachments
• Version Control: Version-specific data retrieval

Quick Reference:

• See authenticationExamples() for Context JWT and project enablement
• See configOperationsExamples() for custom fields, labels, iterations, and data sets
• See archiveConfigExamples() for archiving/unarchiving config items
• See testCaseVersionExamples() for creating test case versions
• See attachmentExamples() for uploading attachments
• See versionSpecificDataExamples() for version-specific data retrieval
• See extendedDataExamples() for supplementing public API with extended data
• See testCaseArchivingExamples() for test case archiving operations
• See testScriptDataExamples() for managing test script data (Parameters and Test Data)
• See testStepsWithVersionExamples() for test steps with version support
• See testExecutionsWithTestDataExamples() for advanced test execution operations
• See listAllTestExecutionsExamples() for listing all test executions across versions

Notes:

• Version numbers are absolute (1-based). Use listTestCaseVersions() to find available versions. If version is not provided, the latest version is used.
• Private API methods require PrivateApiCredentials (userEmail, apiToken, jiraInstanceUrl). Context JWT tokens expire after 15 minutes and are automatically retrieved internally.
• Methods accept keys (e.g., testCaseKey) and automatically look up numeric IDs when needed.
• Deprecated paths still work but will be removed in v2.0.0 - use the new entity-based paths for better organization.

Contact

Contact

Feel free to drop ideas, suggestions or improvements into our Community hub.

Changelog

1.4.3

• Fixed: createTestExecutionWithVersion() now automatically adds the test case to the test cycle if it's not already present (matching public API behavior). This ensures executions can be created for older test case versions even if they weren't previously added to the cycle. The function now properly handles the complete workflow: adding the test case to the cycle (if needed) before creating the execution.

1.4.2

• Added: Delete comment methods - deleteTestCaseComment(), deleteTestCycleComment(), deleteTestPlanComment(). All support version-specific operations for test cases.
• Added: Delete attachment methods - deleteTestCaseAttachment(), deleteTestCycleAttachment(), deleteTestPlanAttachment(), deleteTestStepAttachment(). All support version-specific operations for test cases and test steps.
• Added: Delete link methods - deleteTestCaseWebLink(), deleteTestCaseIssueLink(), deleteTestCycleWebLink(), deleteTestCycleIssueLink(), deleteTestPlanWebLink(), deleteTestPlanIssueLink(). All support version-specific operations for test cases.
• Added: Update test script methods with version support - updateTestCasePlainTextScriptWithVersion(), updateTestCaseBddScriptWithVersion(). These allow updating BDD and Plain text scripts for older test case versions (public API only supports latest version).
• Added: Version support for test case parameter/test data methods - setTestCaseParamTypeToParameter(), setTestCaseParameters(), setTestCaseParamTypeToTestData(), setTestCaseTestData(), getTestCaseTestData(), hasTestCaseTestData() now all support an optional version parameter.
• Added: Version support for createTestCaseTestStepsWithVersion() - Now supports an optional version parameter for the test case itself, in addition to version support for call-to-test steps.
• Added: Version support for test case comment and attachment creation methods - createTestCaseComment() and createTestCaseAttachment() now support an optional version parameter.
• Added: New Private.TestPlan group - Consolidates test plan-related private API operations (delete web/issue links).
• Added: AI_AGENT_GUIDE.md - Comprehensive guide for AI coding agents covering all API functions, capabilities, limitations, and best practices. This file is included in the NPM package and visible on the NPM website.
• Changed: All test case-related private API methods that accept a test case key now support an optional version parameter. When a version is specified, the method automatically resolves the test case ID for that specific version.

1.4.1

• Added: listAllTestExecutionsForTestCase() - List all test executions for a test case across all versions. Unlike the public API which only returns executions for the latest version, this method returns executions from all test case versions. Returns minimal data (key and testCase info) - use the public API to get full execution details if needed.
• Added: getTestCaseTestStepsWithIds() - Get test case test steps with step IDs included. Unlike the public API which doesn't return step IDs, this method provides IDs needed for updating steps. Also includes call-to-test step information with test case IDs and versions.
• Added: createTestCaseTestStepsWithVersion() - Create or update test case test steps with version support for call-to-test steps. Unlike the public API which only allows test case keys (always uses latest version), this method allows specifying a version for call-to-test steps, enabling references to older test case versions.
• Added: Helper method getFullTestCaseData() in PrivateBase - Reusable method for fetching comprehensive test case data including all metadata, test script with step IDs, test data, parameters, and all other available fields. Used internally by multiple private API methods to ensure consistency and reduce code duplication.
• Refactored: Consolidated duplicate test case data fetching logic across PrivateVersionControl, PrivateAttachments, and PrivateTestCase methods to use the centralized getFullTestCaseData() helper method.

1.4.0

• Changed: Major structural reorganization of Private API to follow entity-based grouping (mirrors public API organization)
  • New Entity-Based Groups: Private.TestCase, Private.TestCycle, Private.TestExecution
  • Private.TestCase: Consolidates Archiving, TestScriptData, and Versions sub-groups
  • Private.TestCycle: Adds ExtendedData sub-group for iteration operations
  • Private.TestExecution: Consolidates all test execution operations and adds ExtendedData sub-group for iteration and version operations
• Added: createTestExecutionWithVersion() - Create test execution for a specific test case version (not just latest version). Unlike the public API which only creates executions against the latest test case version, this function allows creating executions against any version of a test case.
• Deprecated: Old feature-based paths are deprecated but still functional (will be removed in v2.0.0):
  • Private.TestExecutions.* → Use Private.TestExecution.* instead
  • Private.ExtendedData.* → Use Private.TestCycle.ExtendedData.* or Private.TestExecution.ExtendedData.* instead
  • Private.TestCaseArchiving.* → Use Private.TestCase.Archiving.* instead
  • Private.TestScriptData.* → Use Private.TestCase.TestScriptData.* instead
  • Private.Versions.* → Use Private.TestCase.Versions.* instead

1.3.11

• Added: Verbose logging option - Enable detailed request/response logging for failed API calls via createZephyrApi(connection, true) or createZephyrApi(token, baseUrl, true)

1.3.10

• Added: New TestScriptData sub-group under Private API for managing test script data (Parameters and Test Data)
• Added: setTestCaseParamTypeToParameter() - Set test case param type to Parameter
• Added: setTestCaseParameters() - Set parameters array for a test case
• Added: setTestCaseParamTypeToTestData() - Set test case param type to Test Data
• Added: setTestCaseTestData() - Set test data array for a test case (simplified array format)
• Added: getTestCaseTestData() - Get test script data (paramType, parameters, testData) for a test case
• Added: hasTestCaseTestData() - Check if test case has test script data (Parameters or Test Data)
• Added: New TestExecutions sub-group under Private API for creating and updating test executions for test cases with test data
• Added: createTestExecutionWithTestData() - Create test execution for test case with test data (handles full workflow automatically)
• Added: getTestCycleItems() - Get test cycle items (testRunItems) for a test cycle
• Added: updateTestExecution() - Update parent test execution information
• Added: getTestExecutionSteps() - Get test execution steps (returns only IDs and basic info needed for updates)
• Added: updateTestExecutionStepStatus() - Update test execution step status
• Added: updateTestExecutionStepComment() - Update test execution step comment (actual result)
• Added: enableZephyrForProject() - Enable Zephyr for a Jira project (under Authentication sub-group)
• Added: isZephyrEnabledForProject() - Check if Zephyr is enabled for a Jira project (under Authentication sub-group)

1.3.9

• Changed: Readme fixes

1.3.8

• Added: getTestExecutionVersion() - Get Jira version ID (release version) for a test execution (supplements public getTestExecution())
• Added: updateTestExecutionVersion() - Set/clear Jira version ID for a test execution (supplements public createTestExecution()/updateTestExecution())
• Added: New TestCaseArchiving sub-group under Private API for test case archiving operations
• Added: getArchivedTestCases() - Get paginated list of archived test cases (supplements public API which doesn't expose archived flag)
• Added: archiveTestCases() - Archive one or more test cases (bulk operation)
• Added: unarchiveTestCases() - Unarchive one or more test cases (bulk operation)
• Changed: Renamed IterationData sub-group to ExtendedData to better reflect that it handles both iteration and version data

1.3.7

• Added: New ExtendedData sub-group under Private API to supplement public API with extended data (iterations and versions)
• Added: getTestCycleIteration() - Get iteration for a test cycle (supplements public getTestCycle())
• Added: updateTestCycleIteration() - Set/clear iteration for a test cycle (supplements public createTestCycle()/updateTestCycle())
• Added: getTestExecutionIteration() - Get iteration for a test execution (supplements public getTestExecution())
• Added: updateTestExecutionIteration() - Set/clear iteration for a test execution (supplements public createTestExecution()/updateTestExecution())
• Added: Support for archiving/unarchiving statuses in archiveConfig() and unarchiveConfig() methods
• Added: New config types: 'TestCaseStatus', 'TestPlanStatus', 'TestCycleStatus', 'TestExecutionStatus'
• Changed: archiveConfig() and unarchiveConfig() now support archiving statuses in addition to Environments and Iterations
• Fixed: createTestExecution() now correctly returns Promise<void> instead of Promise<CreatedResource>, matching the actual API response

1.3.6

• Fixed: Corrected return types for createPriority(), createStatus(), createEnvironment(), and createFolder() - these methods now correctly return CreatedResource (id and self) instead of full entity objects, matching the actual API response

1.3.4

• Added: getTestExecutionStepIssueLinks() - Get issue links for a test execution step (for migration purposes)
• Added: createTestExecutionStepIssueLink() - Create an issue link for a test execution step

1.3.3

• Added: New VersionControl sub-group under Private API for version-specific operations
• Added: getTestCaseIssueLinks() - Get issue links for a test case with version support
• Added: getTestCaseWebLinks() - Get web links for a test case with version support
• Added: getTestCaseTestScript() - Get test script for a test case with version support
• Added: getTestCaseTestSteps() - Get test steps for a test case with version support
• Added: Version parameter support to getTestCaseComments(), getTestCaseAttachments(), and downloadAttachment() methods
• Changed: Private API now organized as: Authentication, Comments, Config, Versions, Attachments, VersionControl

1.3.2

• Changed: updateDataSet now takes id in the request object instead of as a separate parameter
• Changed: Removed unused color, index, and items parameters from createLabel, createIteration, and createDataSet request types (these are now hardcoded internally)

1.3.1

• Added: New Config sub-group under Private API for configuration operations
• Added: Labels endpoints (getLabels, createLabel)
• Added: Iterations endpoints (getIterations, createIteration)
• Added: DataSets endpoints (getDataSets, createDataSet, updateDataSet)
• Changed: CustomFields moved to Private.Config.CustomFields (backward compatible path removed)
• Changed: Private API now organized as: Authentication, Comments, Config (CustomFields, Labels, Iterations, DataSets), Versions, Attachments

1.3.0

• Tested: All API functions from the Private API have been tested and verified - 16/12/2025

1.2.9

• Changed: Test step and test execution step attachment methods now use stepIndex (zero-based array index) instead of stepId/testScriptResultId for better usability
• Changed: Renamed createAttachment to createTestCaseAttachment to match naming convention with other attachment methods
• Removed: All deprecated methods from Private group - use sub-groups (Private.Comments, Private.Attachments, etc.) instead
• Fixed: Corrected API documentation URLs in README to use proper tag-based format

1.2.8

• Added: Attachment support for test steps, test executions, and test execution steps
• Changed: Updated PrivateBase to include TestExecutionGroup for test execution key-to-ID lookups

1.2.7

• Added: Attachment support for test cycles and test plans

1.2.6

• Added: createTestCycleComment() and createTestPlanComment() methods
• Changed: Private API reorganized into sub-groups for better organization

1.2.5

• Added: getTestPlanComments() method
• Changed: Private API reorganized into sub-groups (Authentication, Comments, CustomFields, Versions, Attachments)

1.2.4

• Added: getTestCaseComments() and getTestCycleComments() methods

1.2.3

• Changed: All private API methods now accept a single PrivateApiCredentials interface instead of three separate parameters

1.2.2

• Added: getCustomFields() method for retrieving custom fields
• Added: Support for TEST_EXECUTION category in custom field operations

1.2.1

• Fixed: UUID generation for attachment uploads - replaced crypto.randomUUID() with custom implementation compatible with ScriptRunner Connect runtime

1.2.0

• Added: Private API group with support for unofficial Zephyr endpoints
  • getContextJwt() - Retrieve Jira Context JWT token
  • createCustomField() - Create custom fields for test cases, test plans, test runs, test steps, and test executions
  • createTestCaseVersion() - Create new test case versions
  • createTestCaseComment() - Create comments on test cases
  • getTestCaseAttachments() - Get all attachment details for a test case
  • downloadAttachment() - Download attachment files into memory
  • createAttachment() - Upload file attachments to test cases

1.0.1

• Added: Comprehensive JSDoc comments with API endpoint descriptions
• Added: Single import option via default export
• Changed: Removed region parameter from createZephyrApi - base URL now configured in Generic Connector

1.0.0

• Initial Release: Complete Managed API wrapper for Zephyr Cloud REST API v2
• Added: Full support for all Zephyr API endpoints
• Added: Type-safe TypeScript definitions
• Added: Hierarchical API structure matching ScriptRunner Connect conventions
• Added: Automatic rate limiting retry with exponential backoff
• Added: Support for both API Connection and OAuth token authentication

Copyright Adaptavist 2025 (c) All rights reserved