@rbaileysr/zephyr-managed-api 1.4.0 → 1.4.1

package/README.md

@@ -181,11 +181,12 @@ Response Details: {
       - **Archiving**: `getArchivedTestCases`, `archiveTestCases`, `unarchiveTestCases`
       - **TestScriptData**: `setTestCaseParamTypeToParameter`, `setTestCaseParameters`, `setTestCaseParamTypeToTestData`, `setTestCaseTestData`, `getTestCaseTestData`, `hasTestCaseTestData`
       - **Versions**: `createTestCaseVersion`
+      - **Methods**: `getTestCaseTestStepsWithIds`, `createTestCaseTestStepsWithVersion`
   - ### TestCycle (entity-based group - v1.4.0+)
       - **ExtendedData**: `getTestCycleIteration`, `updateTestCycleIteration`
   - ### TestExecution (entity-based group - v1.4.0+)
       - **ExtendedData**: `getTestExecutionIteration`, `updateTestExecutionIteration`, `getTestExecutionVersion`, `updateTestExecutionVersion`
-      - **Methods**: `createTestExecutionWithTestData`, `createTestExecutionWithVersion`, `updateTestExecution`, `getTestExecutionSteps`, `updateTestExecutionStepStatus`, `updateTestExecutionStepComment`, `getTestCycleItems`
+      - **Methods**: `listAllTestExecutionsForTestCase`, `createTestExecutionWithTestData`, `createTestExecutionWithVersion`, `updateTestExecution`, `getTestExecutionSteps`, `updateTestExecutionStepStatus`, `updateTestExecutionStepComment`, `getTestCycleItems`
   - ### Versions (deprecated - use `Private.TestCase.Versions` instead)
       - **createTestCaseVersion** - Create a new test case version
   - ### Attachments
@@ -215,8 +216,9 @@ Private API methods require Jira user credentials (email and API token) rather t
 
 ### Get Context JWT
 
-The Context JWT is a short-lived token (15 minutes) required for all private API calls:
+The Context JWT is a short-lived token (15 minutes) required for all private API calls. See [`examples.ts`](./examples.ts) for comprehensive usage examples.
 
+**Basic Usage:**
 ```typescript
 import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
 import ZephyrApiConnection from '../api/zephyr';
@@ -232,369 +234,41 @@ const credentials = {
 
 // Get Context JWT token
 const contextJwt = await api.Private.Authentication.getContextJwt(credentials);
-
-// Check if Zephyr is enabled for a project
-const status = await api.Private.Authentication.isZephyrEnabledForProject(credentials, {
-  projectId: 10349
-});
-// Returns: { id: 10349, key: 'D1', permissionSystemEnabled: false, kanoahTestsEnabled: true, active: 1 }
-
-// Enable Zephyr for a project
-await api.Private.Authentication.enableZephyrForProject(credentials, {
-  projectId: 10349
-});
-```
-
-### Example: Config Operations
-
-```typescript
-// Create custom field
-const customField = await api.Private.Config.CustomFields.createCustomField(
-  credentials, 'TEST_CASE', {
-    projectId: 10017,
-    name: 'Build Number',
-    type: 'SINGLE_LINE_TEXT',
-    required: false
-  }
-);
-
-// Create label
-await api.Private.Config.Labels.createLabel(credentials, {
-  projectId: 10233,
-  name: 'automated'
-});
-
-// Create iteration
-const iteration = await api.Private.Config.Iterations.createIteration(credentials, {
-  projectId: 10233,
-  name: 'Sprint 1',
-  description: 'First sprint of Q1'
-});
-
-// Create and update data set
-const dataSet = await api.Private.Config.DataSets.createDataSet(credentials, {
-  projectId: 10233,
-  name: 'Environment'
-});
-await api.Private.Config.DataSets.updateDataSet(credentials, {
-  id: dataSet.id,
-  projectId: 10233,
-  items: [
-    { name: 'Production', index: 0, archived: false },
-    { name: 'Staging', index: 1, archived: false }
-  ]
-});
-```
-
-### Example: Archive and Unarchive Config Items
-
-```typescript
-// Archive an environment or iteration
-await api.Private.Config.archiveConfig(credentials, {
-  type: 'Environment',
-  id: 10873400,
-  projectId: 10233
-});
-
-// Archive statuses (supports: TestCaseStatus, TestPlanStatus, TestCycleStatus, TestExecutionStatus)
-await api.Private.Config.archiveConfig(credentials, {
-  type: 'TestCaseStatus',
-  id: 10952238,
-  projectId: 10313
-});
-
-// Unarchive any config item (same types supported)
-await api.Private.Config.unarchiveConfig(credentials, {
-  type: 'Iteration',
-  id: 10909775,
-  projectId: 10233
-});
-```
-
-### Example: Create Test Case Version
-
-```typescript
-// Create a new version of an existing test case (v1.4.0+)
-const newVersion = await api.Private.TestCase.Versions.createTestCaseVersion(
-  credentials,
-  {
-    testCaseKey: 'PROJ-T1',  // Uses key, looks up ID automatically
-    projectId: 10017          // Numeric project ID
-  }
-);
-```
-
-**Note:** The old path (`Private.Versions.createTestCaseVersion`) still works but is deprecated. Use `Private.TestCase.Versions.createTestCaseVersion` for better organization.
-
-### Example: Upload Attachment
-
-```typescript
-// Upload an attachment to a test case
-const file = new Blob(['file content'], { type: 'text/plain' });
-
-const attachment = await api.Private.Attachments.createTestCaseAttachment(
-  credentials,
-  {
-    testCaseKey: 'PROJ-T1',
-    projectId: 10233,
-    file: file,
-    fileName: 'test-file.txt',
-    userAccountId: '5d6fdc98dc6e480dbc021aae'  // Atlassian account ID
-  }
-);
-```
-
-### Example: Version-Specific Data
-
-```typescript
-// Get version-specific data for test cases (version parameter is optional, defaults to latest)
-const issueLinks = await api.Private.VersionControl.getTestCaseIssueLinks(credentials, {
-  testCaseKey: 'PROJ-T1',
-  projectId: 10233,
-  version: 2  // Get links for version 2
-});
-
-const testScript = await api.Private.VersionControl.getTestCaseTestScript(credentials, {
-  testCaseKey: 'PROJ-T1',
-  projectId: 10233,
-  version: 3
-});
-
-// Test execution step issue links
-const stepLinks = await api.Private.VersionControl.getTestExecutionStepIssueLinks(credentials, {
-  testExecutionKey: 'PROJ-E1',
-  stepIndex: 0,
-  projectId: 10233
-});
-
-await api.Private.VersionControl.createTestExecutionStepIssueLink(credentials, {
-  testExecutionKey: 'PROJ-E1',
-  stepIndex: 0,
-  issueId: 66019,
-  projectId: 10233
-});
-// Note: Link type is always 'RELATED' (typeId 3) - the API does not support choosing link types
 ```
 
-### Example: Extended Data (Supplements Public API)
-
-The public API does not support iterations for Test Cycles/Executions or Jira version IDs for Test Executions. Use entity-based groups (v1.4.0+) to supplement public API calls.
-
-```typescript
-// Test Cycle: Set/get iteration (v1.4.0+)
-const testCycle = await api.TestCycle.createTestCycle({
-  projectKey: 'M12',
-  name: 'Sprint 1 Testing'
-});
-await api.Private.TestCycle.ExtendedData.updateTestCycleIteration(credentials, {
-  testCycleKey: testCycle.key,
-  projectId: 10313,
-  iterationId: 10952254
-});
-const cycleIteration = await api.Private.TestCycle.ExtendedData.getTestCycleIteration(credentials, {
-  testCycleKey: 'M12-R1',
-  projectId: 10313
-});
-
-// Test Execution: Set/get iteration and version (v1.4.0+)
-await api.TestExecution.createTestExecution({
-  projectKey: 'M12',
-  testCaseKey: 'M12-T1',
-  testCycleKey: 'M12-R1',
-  statusName: 'Pass'
-});
-// Note: createTestExecution returns void - use known key or look up via listTestExecutions()
-await api.Private.TestExecution.ExtendedData.updateTestExecutionIteration(credentials, {
-  testExecutionKey: 'M12-E1',
-  projectId: 10313,
-  iterationId: 10952254
-});
-await api.Private.TestExecution.ExtendedData.updateTestExecutionVersion(credentials, {
-  testExecutionKey: 'M15-E3',
-  projectId: 10316,
-  jiraVersionId: 10102
-});
-
-// Clear by setting to null
-await api.Private.TestCycle.ExtendedData.updateTestCycleIteration(credentials, {
-  testCycleKey: 'M12-R1',
-  projectId: 10313,
-  iterationId: null
-});
-```
-
-**Note:** The old paths (`Private.ExtendedData.*`) still work but are deprecated. Use the new entity-based paths (`Private.TestCycle.ExtendedData.*` and `Private.TestExecution.ExtendedData.*`) for better organization.
-
-### Example: Test Case Archiving
-
-The public API does not expose the archived flag. Use `Private.TestCase.Archiving` (v1.4.0+) to list, archive, and unarchive test cases.
-
-```typescript
-// Get archived test cases (paginated, optional query filter)
-const archived = await api.Private.TestCase.Archiving.getArchivedTestCases(credentials, {
-  projectId: 10316,
-  maxResults: 50,
-  startAt: 0,
-  query: "testCase.name CONTAINS 'migration'"  // optional
-});
-
-// Archive test cases (single or multiple)
-await api.Private.TestCase.Archiving.archiveTestCases(credentials, {
-  projectId: 10316,
-  testCaseIds: [288004503, 288004504, 288004505]
-});
-
-// Unarchive test cases
-await api.Private.TestCase.Archiving.unarchiveTestCases(credentials, {
-  projectId: 10316,
-  testCaseIds: [288004503]
-});
-```
-
-**Note:** The old path (`Private.TestCaseArchiving.*`) still works but is deprecated. Use `Private.TestCase.Archiving.*` for better organization.
-
-### Test Script Data
-
-The public API does not expose test script data (Parameters and Test Data). Use `Private.TestCase.TestScriptData` (v1.4.0+) to manage this data.
-
-```typescript
-// Check if test case has test script data
-const hasData = await api.Private.TestCase.TestScriptData.hasTestCaseTestData(credentials, {
-  testCaseKey: 'M14-T6',
-  projectId: 10315
-});
-// Returns: { hasData: true, type: 'PARAMETER' } or { hasData: false, type: null }
-
-// Get test script data
-const testData = await api.Private.TestCase.TestScriptData.getTestCaseTestData(credentials, {
-  testCaseKey: 'M14-T6',
-  projectId: 10315
-});
-// Returns: { paramType: 'PARAMETER' | 'TEST_DATA' | null, parameters: [...], testData: [...] }
-
-// Set test case to use Parameters
-await api.Private.TestCase.TestScriptData.setTestCaseParamTypeToParameter(credentials, {
-  testCaseKey: 'M14-T6',
-  projectId: 10315
-});
-
-// Set parameters
-await api.Private.TestCase.TestScriptData.setTestCaseParameters(credentials, {
-  testCaseKey: 'M14-T6',
-  projectId: 10315,
-  parameters: [
-    { index: 0, name: 'param1', defaultValue: 'value1' },
-    { index: 1, name: 'param2', defaultValue: 'value2' }
-  ]
-});
-
-// Set test case to use Test Data
-await api.Private.TestCase.TestScriptData.setTestCaseParamTypeToTestData(credentials, {
-  testCaseKey: 'M14-T6',
-  projectId: 10315
-});
-
-// Set test data (simplified array format)
-await api.Private.TestCase.TestScriptData.setTestCaseTestData(credentials, {
-  testCaseKey: 'M14-T6',
-  projectId: 10315,
-  testData: [
-    // Row 1
-    [
-      { columnName: 'Dataset Column', type: 'data_set', index: 0, dataSetItemId: 936037 },
-      { columnName: 'Custom Column', type: 'free_text_input', index: 1, value: 'test value' }
-    ]
-  ]
-});
-```
-
-**Note:** The old path (`Private.TestScriptData.*`) still works but is deprecated. Use `Private.TestCase.TestScriptData.*` for better organization.
-
-### Test Executions with Test Data
-
-The public API does not correctly handle creating test executions for test cases with test data or test cases with "Call to Test" steps that reference test cases with test data. Use `Private.TestExecution` (v1.4.0+) to create and update these executions.
-
-```typescript
-// Create test execution for test case with test data
-// This automatically handles the two-step process:
-// 1. Creates execution via public API
-// 2. Gets testRunItemId from private API
-// 3. Creates actual execution via private API
-const execution = await api.Private.TestExecution.createTestExecutionWithTestData(credentials, {
-  testCaseKey: 'M14-T6',
-  testCycleKey: 'M14-R1',
-  assignedTo: '5d259f2e0b81c60c239bed83', // optional
-  projectId: 10315
-});
-// Returns: { id: 2065132733, key: 'M14-E18' }
-
-// Create test execution for specific test case version (not just latest)
-// Unlike the public API which only creates executions against the latest version,
-// this allows creating executions against any version of a test case
-const executionWithVersion = await api.Private.TestExecution.createTestExecutionWithVersion(credentials, {
-  body: {
-    projectKey: 'M14',
-    testCaseKey: 'M14-T6',
-    testCycleKey: 'M14-R1',
-    statusName: 'Not Executed',
-    version: 2, // Create execution against version 2 of the test case
-    environmentName: 'Production', // optional
-    assignedToId: '5d259f2e0b81c60c239bed83', // optional
-    comment: 'Testing version 2', // optional
-  },
-  projectId: 10315,
-  assignedTo: '5d259f2e0b81c60c239bed83', // optional, can override body.assignedToId
-  iterationId: 10966272, // optional
-  jiraVersionId: 10206 // optional
-});
-// Returns: { id: 2068847141, key: 'M2-E13' }
-
-// Get test cycle items (to find testRunItemId for a test case)
-const items = await api.Private.TestExecution.getTestCycleItems(credentials, {
-  testCycleKey: 'M14-R1',
-  projectId: 10315
-});
-
-// Update parent test execution
-await api.Private.TestExecution.updateTestExecution(credentials, {
-  testExecutionKey: 'M14-E18',
-  id: 2065132733, // Optional if testExecutionKey is provided
-  actualStartDate: '2025-12-24T13:02:50.233Z',
-  executionDate: '2025-12-24T13:02:50.233Z',
-  executionTime: 0,
-  testResultStatusId: 10952941,
-  projectId: 10315
-});
-
-// Get test execution steps (to get step IDs for updates)
-const steps = await api.Private.TestExecution.getTestExecutionSteps(credentials, {
-  testCycleKey: 'M14-R1',
-  testRunItemId: 1443476310, // From getTestCycleItems
-  projectId: 10315
-});
-
-// Update test execution step status
-await api.Private.TestExecution.updateTestExecutionStepStatus(credentials, {
-  id: 6287896613, // From getTestExecutionSteps
-  testResultStatusId: 10952942,
-  executionDate: '2025-12-24T13:02:50.232Z',
-  projectId: 10315
-});
-
-// Update test execution step comment (actual result)
-await api.Private.TestExecution.updateTestExecutionStepComment(credentials, {
-  id: 6287896613, // From getTestExecutionSteps
-  comment: 'Test passed successfully',
-  projectId: 10315
-});
-```
-
-**Note:** The old path (`Private.TestExecutions.*`) still works but is deprecated. Use `Private.TestExecution.*` for better organization.
+## Private API Examples
+
+Comprehensive examples for all private API methods are available in [`examples.ts`](./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
 
@@ -602,6 +276,14 @@ Feel free to drop ideas, suggestions or improvements into our [Community hub](ht
 
 ## Changelog
 
+### 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)