0
# Development Tools
1
2
Comprehensive CI/CD and test management tools including Bamboo for build automation and X-Ray for test execution and reporting. Enables integration of Atlassian development tools into automated workflows and quality assurance processes.
3
4
## Bamboo - CI/CD Build Management
5
6
Bamboo REST API client providing complete build pipeline management, plan execution, and artifact handling for continuous integration and deployment workflows.
7
8
### Initialization
9
10
```python { .api }
11
class Bamboo(AtlassianRestAPI):
12
def __init__(self, url: str, username: str = None, password: str = None,
13
token: str = None, **kwargs):
14
"""
15
Initialize Bamboo client.
16
17
Parameters:
18
- url (str): Base URL of Bamboo instance
19
- username (str, optional): Username for authentication
20
- password (str, optional): Password or API token
21
- token (str, optional): Bearer token for authentication
22
"""
23
```
24
25
### Build Management
26
27
```python { .api }
28
def get_builds(self, project_key: Optional[str] = None,
29
plan_key: Optional[str] = None,
30
start: int = 0, limit: int = 25) -> T_resp_json:
31
"""
32
Get builds with optional filtering.
33
34
Parameters:
35
- project_key: Filter by project key
36
- plan_key: Filter by plan key
37
- start: Starting index for pagination
38
- limit: Maximum results to return
39
40
Returns:
41
dict: Build list with status and timing information
42
"""
43
44
def get_build(self, build_key: str) -> T_resp_json:
45
"""
46
Get build details.
47
48
Parameters:
49
- build_key: Build key (e.g., "PROJ-PLAN-123")
50
51
Returns:
52
dict: Build information with logs and artifacts
53
"""
54
55
def start_build(self, plan_key: str, **kwargs) -> T_resp_json:
56
"""
57
Start build execution.
58
59
Parameters:
60
- plan_key: Plan key to execute
61
- **kwargs: Additional build parameters
62
63
Returns:
64
dict: Started build information
65
"""
66
67
def stop_build(self, build_key: str) -> T_resp_json:
68
"""
69
Stop running build.
70
71
Parameters:
72
- build_key: Build key to stop
73
74
Returns:
75
dict: Stop operation result
76
"""
77
78
def get_build_status(self, build_key: str) -> T_resp_json:
79
"""
80
Get build status.
81
82
Parameters:
83
- build_key: Build key
84
85
Returns:
86
dict: Current build status and progress
87
"""
88
```
89
90
### Plan Management
91
92
```python { .api }
93
def get_plans(self, project_key: Optional[str] = None,
94
start: int = 0, limit: int = 25) -> T_resp_json:
95
"""
96
Get build plans.
97
98
Parameters:
99
- project_key: Filter by project
100
- start: Starting index
101
- limit: Maximum results
102
103
Returns:
104
dict: Plans list with configuration
105
"""
106
107
def get_plan(self, plan_key: str) -> T_resp_json:
108
"""
109
Get plan details.
110
111
Parameters:
112
- plan_key: Plan key
113
114
Returns:
115
dict: Plan configuration and branches
116
"""
117
118
def create_plan(self, project_key: str, plan_name: str, plan_key: str,
119
description: Optional[str] = None) -> T_resp_json:
120
"""
121
Create build plan.
122
123
Parameters:
124
- project_key: Project key
125
- plan_name: Plan display name
126
- plan_key: Unique plan key
127
- description: Plan description
128
129
Returns:
130
dict: Created plan data
131
"""
132
133
def clone_plan(self, plan_key: str, new_plan_key: str,
134
new_plan_name: str) -> T_resp_json:
135
"""
136
Clone existing plan.
137
138
Parameters:
139
- plan_key: Source plan key
140
- new_plan_key: New plan key
141
- new_plan_name: New plan name
142
143
Returns:
144
dict: Cloned plan information
145
"""
146
147
def enable_plan(self, plan_key: str) -> T_resp_json:
148
"""
149
Enable build plan.
150
151
Parameters:
152
- plan_key: Plan key to enable
153
154
Returns:
155
dict: Operation result
156
"""
157
158
def disable_plan(self, plan_key: str) -> T_resp_json:
159
"""
160
Disable build plan.
161
162
Parameters:
163
- plan_key: Plan key to disable
164
165
Returns:
166
dict: Operation result
167
"""
168
```
169
170
### Results and Artifacts
171
172
```python { .api }
173
def get_results(self, plan_key: str, build_number: Optional[int] = None,
174
start: int = 0, limit: int = 25) -> T_resp_json:
175
"""
176
Get build results.
177
178
Parameters:
179
- plan_key: Plan key
180
- build_number: Specific build number
181
- start: Starting index
182
- limit: Maximum results
183
184
Returns:
185
dict: Build results with test outcomes
186
"""
187
188
def get_latest_results(self, plan_key: str) -> T_resp_json:
189
"""
190
Get latest build results.
191
192
Parameters:
193
- plan_key: Plan key
194
195
Returns:
196
dict: Most recent build results
197
"""
198
199
def get_artifacts(self, build_key: str) -> T_resp_json:
200
"""
201
Get build artifacts.
202
203
Parameters:
204
- build_key: Build key
205
206
Returns:
207
dict: Artifacts list with download URLs
208
"""
209
210
def download_artifact(self, build_key: str, artifact_name: str) -> bytes:
211
"""
212
Download build artifact.
213
214
Parameters:
215
- build_key: Build key
216
- artifact_name: Artifact name
217
218
Returns:
219
bytes: Artifact content
220
"""
221
```
222
223
## X-Ray - Test Management
224
225
X-Ray REST API client providing comprehensive test management including test execution, result reporting, and test plan organization for quality assurance workflows.
226
227
### Initialization
228
229
```python { .api }
230
class Xray(AtlassianRestAPI):
231
def __init__(self, url: str, username: str = None, password: str = None,
232
token: str = None, cloud: bool = None, **kwargs):
233
"""
234
Initialize X-Ray client.
235
236
Parameters:
237
- url (str): Base URL of Jira instance with X-Ray
238
- username (str, optional): Username for authentication
239
- password (str, optional): Password or API token
240
- token (str, optional): Bearer token for authentication
241
- cloud (bool, optional): True for Cloud, False for Server/DC
242
"""
243
```
244
245
### Test Management
246
247
```python { .api }
248
def get_tests(self, project_key: str, test_type: Optional[str] = None,
249
start: int = 0, limit: int = 50) -> T_resp_json:
250
"""
251
Get tests from project.
252
253
Parameters:
254
- project_key: Project key
255
- test_type: Filter by test type ("Manual", "Cucumber", "Generic")
256
- start: Starting index
257
- limit: Maximum results
258
259
Returns:
260
dict: Tests list with details
261
"""
262
263
def get_test(self, test_key: str) -> T_resp_json:
264
"""
265
Get test details.
266
267
Parameters:
268
- test_key: Test issue key
269
270
Returns:
271
dict: Test information with steps and conditions
272
"""
273
274
def create_test(self, project_key: str, summary: str, test_type: str,
275
description: Optional[str] = None,
276
steps: Optional[List[dict]] = None) -> T_resp_json:
277
"""
278
Create test case.
279
280
Parameters:
281
- project_key: Project key
282
- summary: Test summary
283
- test_type: Test type ("Manual", "Cucumber", "Generic")
284
- description: Test description
285
- steps: Test steps for manual tests
286
287
Returns:
288
dict: Created test data
289
"""
290
291
def update_test(self, test_key: str, summary: Optional[str] = None,
292
description: Optional[str] = None,
293
steps: Optional[List[dict]] = None) -> T_resp_json:
294
"""
295
Update test case.
296
297
Parameters:
298
- test_key: Test issue key
299
- summary: New summary
300
- description: New description
301
- steps: Updated test steps
302
303
Returns:
304
dict: Updated test data
305
"""
306
```
307
308
### Test Execution
309
310
```python { .api }
311
def get_test_runs(self, test_key: str, start: int = 0,
312
limit: int = 50) -> T_resp_json:
313
"""
314
Get test execution history.
315
316
Parameters:
317
- test_key: Test issue key
318
- start: Starting index
319
- limit: Maximum results
320
321
Returns:
322
dict: Test runs with results and timestamps
323
"""
324
325
def get_test_runs_in_context(self, test_key: str, test_exec_key: str,
326
start: int = 0, limit: int = 50) -> T_resp_json:
327
"""
328
Get test runs within specific execution context.
329
330
Parameters:
331
- test_key: Test issue key
332
- test_exec_key: Test execution issue key
333
- start: Starting index
334
- limit: Maximum results
335
336
Returns:
337
dict: Contextual test runs
338
"""
339
340
def create_test_execution(self, project_key: str, summary: str,
341
test_keys: List[str],
342
test_plan_key: Optional[str] = None) -> T_resp_json:
343
"""
344
Create test execution.
345
346
Parameters:
347
- project_key: Project key
348
- summary: Execution summary
349
- test_keys: List of test issue keys to execute
350
- test_plan_key: Associated test plan key
351
352
Returns:
353
dict: Created test execution data
354
"""
355
356
def update_test_run_status(self, test_exec_key: str, test_key: str,
357
status: str, comment: Optional[str] = None,
358
defects: Optional[List[str]] = None) -> T_resp_json:
359
"""
360
Update test run status.
361
362
Parameters:
363
- test_exec_key: Test execution key
364
- test_key: Test key
365
- status: Test status ("PASS", "FAIL", "EXECUTING", "TODO", "ABORTED")
366
- comment: Execution comment
367
- defects: Associated defect keys
368
369
Returns:
370
dict: Updated test run result
371
"""
372
```
373
374
### Test Plans
375
376
```python { .api }
377
def get_test_plans(self, project_key: str, start: int = 0,
378
limit: int = 50) -> T_resp_json:
379
"""
380
Get test plans from project.
381
382
Parameters:
383
- project_key: Project key
384
- start: Starting index
385
- limit: Maximum results
386
387
Returns:
388
dict: Test plans list
389
"""
390
391
def get_test_plan(self, test_plan_key: str) -> T_resp_json:
392
"""
393
Get test plan details.
394
395
Parameters:
396
- test_plan_key: Test plan issue key
397
398
Returns:
399
dict: Test plan with associated tests and executions
400
"""
401
402
def create_test_plan(self, project_key: str, summary: str,
403
description: Optional[str] = None) -> T_resp_json:
404
"""
405
Create test plan.
406
407
Parameters:
408
- project_key: Project key
409
- summary: Test plan summary
410
- description: Test plan description
411
412
Returns:
413
dict: Created test plan data
414
"""
415
416
def associate_test_to_test_plan(self, test_plan_key: str,
417
test_keys: List[str]) -> T_resp_json:
418
"""
419
Associate tests with test plan.
420
421
Parameters:
422
- test_plan_key: Test plan issue key
423
- test_keys: List of test issue keys
424
425
Returns:
426
dict: Association result
427
"""
428
```
429
430
### Import and Export
431
432
```python { .api }
433
def import_execution_results(self, execution_results: dict,
434
project_key: Optional[str] = None,
435
test_plan_key: Optional[str] = None) -> T_resp_json:
436
"""
437
Import test execution results.
438
439
Parameters:
440
- execution_results: Results data in X-Ray format
441
- project_key: Target project key
442
- test_plan_key: Associated test plan
443
444
Returns:
445
dict: Import results with created issues
446
"""
447
448
def export_test_results(self, test_exec_key: str,
449
format: str = "json") -> Union[dict, str]:
450
"""
451
Export test execution results.
452
453
Parameters:
454
- test_exec_key: Test execution key
455
- format: Export format ("json", "xml", "junit")
456
457
Returns:
458
dict or str: Exported results in requested format
459
"""
460
461
def import_cucumber_tests(self, project_key: str, file_content: str,
462
update_repository: bool = False) -> T_resp_json:
463
"""
464
Import Cucumber feature files.
465
466
Parameters:
467
- project_key: Project key
468
- file_content: Cucumber feature file content
469
- update_repository: Update existing tests
470
471
Returns:
472
dict: Import results with created/updated tests
473
"""
474
```
475
476
## Usage Examples
477
478
### Bamboo Build Automation
479
480
```python
481
from atlassian import Bamboo
482
483
bamboo = Bamboo(
484
url="https://bamboo.company.com",
485
username="username",
486
password="password"
487
)
488
489
# Get build plans
490
plans = bamboo.get_plans(project_key="PROJ")
491
492
# Start build
493
build = bamboo.start_build("PROJ-PLAN")
494
495
# Monitor build progress
496
build_status = bamboo.get_build_status(build["buildResultKey"])
497
498
# Get build results when complete
499
if build_status["state"] == "Successful":
500
results = bamboo.get_results("PROJ-PLAN")
501
artifacts = bamboo.get_artifacts(build["buildResultKey"])
502
503
# Download artifacts
504
for artifact in artifacts["artifacts"]["artifact"]:
505
content = bamboo.download_artifact(
506
build["buildResultKey"],
507
artifact["name"]
508
)
509
with open(artifact["name"], "wb") as f:
510
f.write(content)
511
```
512
513
### X-Ray Test Management
514
515
```python
516
from atlassian import Xray
517
518
xray = Xray(
519
url="https://your-domain.atlassian.net",
520
username="email@example.com",
521
password="api-token"
522
)
523
524
# Create test case
525
test = xray.create_test(
526
project_key="PROJ",
527
summary="User login functionality",
528
test_type="Manual",
529
description="Verify user can log in with valid credentials",
530
steps=[
531
{
532
"step": "Navigate to login page",
533
"data": "",
534
"result": "Login page displays"
535
},
536
{
537
"step": "Enter valid username and password",
538
"data": "user@example.com, password123",
539
"result": "Credentials accepted"
540
}
541
]
542
)
543
544
# Create test plan
545
test_plan = xray.create_test_plan(
546
project_key="PROJ",
547
summary="Sprint 1 Test Plan",
548
description="Test plan for sprint 1 features"
549
)
550
551
# Associate test with plan
552
xray.associate_test_to_test_plan(
553
test_plan["key"],
554
[test["key"]]
555
)
556
557
# Create and execute test
558
test_execution = xray.create_test_execution(
559
project_key="PROJ",
560
summary="Sprint 1 Test Execution",
561
test_keys=[test["key"]],
562
test_plan_key=test_plan["key"]
563
)
564
565
# Update test results
566
xray.update_test_run_status(
567
test_execution["key"],
568
test["key"],
569
status="PASS",
570
comment="All test steps passed successfully"
571
)
572
```
573
574
### CI/CD Integration
575
576
```python
577
# Automated test execution with Bamboo and X-Ray integration
578
def run_automated_tests(project_key, plan_key):
579
# Start Bamboo build
580
build = bamboo.start_build(plan_key)
581
582
# Wait for build completion
583
while True:
584
status = bamboo.get_build_status(build["buildResultKey"])
585
if status["state"] in ["Successful", "Failed"]:
586
break
587
time.sleep(30)
588
589
# Create X-Ray test execution
590
test_execution = xray.create_test_execution(
591
project_key=project_key,
592
summary=f"Automated Test Run - Build {build['buildNumber']}",
593
test_keys=get_automated_test_keys(project_key)
594
)
595
596
# Import test results from build artifacts
597
if status["state"] == "Successful":
598
artifacts = bamboo.get_artifacts(build["buildResultKey"])
599
for artifact in artifacts["artifacts"]["artifact"]:
600
if artifact["name"].endswith("test-results.json"):
601
results_content = bamboo.download_artifact(
602
build["buildResultKey"],
603
artifact["name"]
604
)
605
results = json.loads(results_content)
606
xray.import_execution_results(
607
results,
608
project_key=project_key
609
)
610
```
611
612
## Error Handling
613
614
```python
615
from atlassian.errors import ApiError, ApiNotFoundError
616
617
try:
618
build = bamboo.start_build("INVALID-PLAN")
619
except ApiNotFoundError:
620
print("Build plan not found")
621
except ApiError as e:
622
print(f"Build failed to start: {e}")
623
```
624
625
## Types
626
627
```python { .api }
628
from atlassian.typehints import T_id, T_resp_json
629
from typing import List, Dict, Optional, Union
630
631
# Bamboo types
632
PlanKey = str
633
BuildKey = str
634
BuildState = str # "Successful", "Failed", "In Progress"
635
636
# X-Ray types
637
TestKey = str
638
TestType = str # "Manual", "Cucumber", "Generic"
639
TestStatus = str # "PASS", "FAIL", "EXECUTING", "TODO", "ABORTED"
640
TestExecutionKey = str
641
TestPlanKey = str
642
```