0
# CI Integration
1

2
Cloud-based CI system integration that posts test results to external APIs during test execution. Provides real-time test result reporting to CI platforms for immediate feedback and build status updates.
3

4
## Capabilities
5

6
### AppVeyor Reporter
7

8
Posts test results to AppVeyor build system via HTTP API with configurable batching and output formatting. Requires AppVeyor environment to be properly configured with API endpoint information.
9

10
```javascript { .api }
11
/**
12
 * Creates an AppVeyor reporter instance that posts results to AppVeyor API
13
 * @param options - Configuration options for AppVeyor integration
14
 * @returns Reporter instance implementing Jasmine reporter interface
15
 */
16
function AppVeyorReporter(options?: AppVeyorOptions): Reporter;
17

18
interface AppVeyorOptions {
19
  /** Spec batch size to report to AppVeyor, higher values reduce API calls (default: 50) */
20
  batchSize?: number;
21
  /** Verbosity level 0-2+, controls logging output (default: 0) */
22
  verbosity?: number;
23
  /** Enable colored console output for logging (default: true) */
24
  color?: boolean;
25
}
26
```
27

28
**Environment Requirements:**
29

30
The AppVeyor reporter requires the `APPVEYOR_API_URL` environment variable to be set by the AppVeyor build environment. This is automatically provided when running in AppVeyor CI.
31

32
**Usage Examples:**
33

34
```javascript
35
// Basic AppVeyor integration with default settings
36
const appveyorReporter = new jasmineReporters.AppVeyorReporter();
37
jasmine.getEnv().addReporter(appveyorReporter);
38

39
// Custom batch size and verbose logging
40
const appveyorReporter = new jasmineReporters.AppVeyorReporter({
41
    batchSize: 25,
42
    verbosity: 2,
43
    color: true
44
});
45

46
// High-throughput configuration for large test suites
47
const appveyorReporter = new jasmineReporters.AppVeyorReporter({
48
    batchSize: 100,
49
    verbosity: 0,
50
    color: false
51
});
52
```
53

54
### API Integration Details
55

56
The AppVeyor reporter communicates with the AppVeyor Test API to report test results in real-time.
57

58
```javascript { .api }
59
/**
60
 * Internal API configuration derived from environment variables
61
 */
62
interface AppVeyorApi {
63
  /** API host extracted from APPVEYOR_API_URL */
64
  host: string;
65
  /** API port extracted from APPVEYOR_API_URL */  
66
  port: string;
67
  /** API endpoint path for batch test reporting */
68
  endpoint: string; // "/api/tests/batch"
69
}
70

71
/**
72
 * Test result format sent to AppVeyor API
73
 */
74
interface AppVeyorTestResult {
75
  /** Full qualified test name including suite and spec names */
76
  testName: string;
77
  /** Testing framework identifier */
78
  testFramework: "jasmine2";
79
  /** Test execution duration in milliseconds */
80
  durationMilliseconds: number;
81
  /** Test outcome using AppVeyor terminology */
82
  outcome: "Passed" | "Failed" | "Skipped" | "Ignored" | "None";
83
  /** Error message from first failed expectation (if any) */
84
  ErrorMessage?: string;
85
  /** Stack trace from first failed expectation (if any) */
86
  ErrorStackTrace?: string;
87
}
88
```
89

90
### HTTP Request Handling
91

92
The reporter uses Node.js `http` module to send POST requests to the AppVeyor API.
93

94
**Request Configuration:**
95
- **Method**: POST
96
- **Content-Type**: application/json
97
- **Endpoint**: `/api/tests/batch`
98
- **Body**: JSON array of test results
99

100
**Error Handling:**
101
- Network errors are logged but don't interrupt test execution
102
- API response errors are logged with status codes and headers when verbosity > 1
103
- Failed requests don't retry automatically
104

105
### Batching Strategy
106

107
Tests are batched to optimize API performance and reduce network overhead.
108

109
**Batching Behavior:**
110
- Results accumulate until batch size is reached
111
- Batch is sent immediately when limit is exceeded  
112
- Remaining results are sent when all tests complete (`jasmineDone`)
113
- Each batch is sent as a separate HTTP request
114

115
**Batch Size Considerations:**
116
- **Small batches (10-25)**: More frequent updates, higher API overhead
117
- **Medium batches (50-100)**: Good balance for most test suites
118
- **Large batches (100+)**: Fewer API calls, delayed feedback
119

120
### Logging and Verbosity
121

122
Configurable logging provides insight into reporter operation and API communication.
123

124
**Verbosity Levels:**
125
- **0 (Silent)**: No logging output
126
- **1 (Info)**: Basic operation messages (batch sending)  
127
- **2+ (Debug)**: Detailed API communication (status codes, headers, response bodies)
128

129
**Color Support:**
130
- Magenta: Batch posting messages
131
- Yellow: API response details  
132
- Red: Error messages
133

134
### Test Result Mapping
135

136
Jasmine test states are mapped to AppVeyor outcome terminology:
137

138
| Jasmine Status | AppVeyor Outcome | Description |
139
|----------------|------------------|-------------|
140
| "passed" | "Passed" | Test executed successfully |
141
| "failed" | "Failed" | Test failed with assertion errors |
142
| "pending" | "Skipped" | Test skipped with `xit()` or `pending()` |
143
| "disabled" | "Ignored" | Test disabled with `xdescribe()` or filtered |
144
145
### Reporter Lifecycle Methods
146

147
```javascript { .api }
148
/** Called when a test spec starts - records start time */
149
specStarted(spec: Spec): void;
150

151
/** Called when a test spec completes - processes result and adds to batch */
152
specDone(spec: Spec): void;
153

154
/** Called when all tests complete - sends remaining batch results */
155
jasmineDone(): void;
156
```
157

158
**State Management:**
159
- Internal spec tracking with start/end times for duration calculation
160
- Unreported specs queue for batching
161
- Automatic batch flushing when size threshold reached
162

163
### Integration Examples
164

165
**AppVeyor Configuration (appveyor.yml):**
166

167
```yaml
168
test_script:
169
  - npm test
170

171
environment:
172
  # APPVEYOR_API_URL is automatically set by AppVeyor
173
```
174

175
**Test Runner Integration:**
176

177
```javascript
178
// spec/support/jasmine.json or similar
179
const reporters = require('jasmine-reporters');
180

181
if (process.env.APPVEYOR) {
182
    const appveyorReporter = new reporters.AppVeyorReporter({
183
        batchSize: 50,
184
        verbosity: 1
185
    });
186
    jasmine.getEnv().addReporter(appveyorReporter);
187
}
188
```
189

190
**Combined with Other Reporters:**
191

192
```javascript
193
// Use AppVeyor reporter alongside terminal output
194
const reporters = require('jasmine-reporters');
195

196
jasmine.getEnv().addReporter(new reporters.TerminalReporter({
197
    verbosity: 2,
198
    color: true
199
}));
200

201
if (process.env.APPVEYOR) {
202
    jasmine.getEnv().addReporter(new reporters.AppVeyorReporter({
203
        batchSize: 75,
204
        verbosity: 0  // Silent to avoid duplicate output
205
    }));
206
}
207
```