/
index.d.ts
685 lines (654 loc) · 24.7 KB
/
index.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
// Type definitions for karma 4.4
// Project: https://github.com/karma-runner/karma, http://karma-runner.github.io
// Definitions by: Tanguy Krotoff <https://github.com/tkrotoff>
// James Garbutt <https://github.com/43081j>
// Yaroslav Admin <https://github.com/devoto13>
// Piotr Błażejewicz <https://github.com/peterblazejewicz>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 3.2
/// <reference types="node" />
// See Karma public API https://karma-runner.github.io/latest/dev/public-api.html
import Promise = require('bluebird');
import https = require('https');
import { Appender } from 'log4js';
import { EventEmitter } from 'events';
import * as constants from './lib/constants';
import { VERSION } from './lib/constants';
export { constants, VERSION };
/**
* `start` method is deprecated since 0.13. It will be removed in 0.14.
* Please use
* <code>
* server = new Server(config, [done])
* server.start()
* </code>
* instead.
*
* @deprecated
*/
export const server: DeprecatedServer;
export const runner: Runner;
export const stopper: Stopper;
export namespace launcher {
class Launcher {
static generateId(): string;
constructor(emitter: NodeJS.EventEmitter, injector: any);
// TODO: Can this return value ever be typified?
launch(names: string[], protocol: string, hostname: string, port: number, urlRoot: string): any[];
kill(id: string, callback: () => void): boolean;
restart(id: string): boolean;
killAll(callback: () => void): void;
areAllCaptured(): boolean;
markCaptured(id: string): void;
}
}
/** @deprecated */
export interface DeprecatedServer {
/** @deprecated */
start(options?: any, callback?: ServerCallback): void;
}
export interface Runner {
run(options?: ConfigOptions | ConfigFile, callback?: ServerCallback): void;
}
export interface Stopper {
/**
* This function will signal a running server to stop. The equivalent of karma stop.
*/
stop(options?: ConfigOptions, callback?: ServerCallback): void;
}
export interface TestResults {
disconnected: boolean;
error: boolean;
exitCode: number;
failed: number;
success: number;
}
export class Server extends EventEmitter {
constructor(options?: ConfigOptions | ConfigFile, callback?: ServerCallback);
/**
* Start the server
*/
start(): void;
/**
* Get properties from the injector
* @param token
*/
get(token: string): any;
/**
* Force a refresh of the file list
*/
refreshFiles(): Promise<any>;
on(event: string, listener: (...args: any[]) => void): this;
/**
* Listen to the 'run_complete' event.
*/
on(event: 'run_complete', listener: (browsers: any, results: TestResults) => void): this;
/**
* Backward-compatibility with karma-intellij bundled with WebStorm.
* Deprecated since version 0.13, to be removed in 0.14
*/
// static start(): void;
}
export type ServerCallback = (exitCode: number) => void;
export interface Config {
set: (config: ConfigOptions) => void;
LOG_DISABLE: string;
LOG_ERROR: string;
LOG_WARN: string;
LOG_INFO: string;
LOG_DEBUG: string;
}
export interface ConfigFile {
configFile: string;
}
// For documentation and intellisense list Karma browsers
/**
* Available browser launchers
* - `Chrome` - launcher requires `karma-chrome-launcher` plugin
* - `ChromeCanary` - launcher requires `karma-chrome-launcher` plugin
* - `ChromeHeadless` - launcher requires `karma-chrome-launcher` plugin
* - `PhantomJS` - launcher requires `karma-phantomjs-launcher` plugin
* - `Firefox` - launcher requires `karma-firefox-launcher` plugin
* - `Opera` - launcher requires `karma-opera-launcher` plugin
* - `IE` - launcher requires `karma-ie-launcher` plugin
* - `Safari` - launcher requires karma-safari-launcher plugin
*/
export type AutomatedBrowsers =
| 'Chrome'
| 'ChromeCanary'
| 'ChromeHeadless'
| 'PhantomJS'
| 'Firefox'
| 'Opera'
| 'IE'
| 'Safari';
export interface CustomHeaders {
/** Regular expression string to match files */
match: string;
/** HTTP header name */
name: string;
/** HTTP header value */
value: string;
}
export interface ProxyOptions {
/** The target url or path (mandatory) */
target: string;
/**
* Whether or not the proxy should override the Host header using the host from the target
* @defult false
*/
changeOrigin?: boolean;
}
/** A map of path-proxy pairs. */
export interface PathProxyPairs {
[path: string]: string | ProxyOptions;
}
/** For use when the Karma server needs to be run behind a proxy that changes the base url, etc */
export interface UpstreamProxy {
/**
* Will be prepended to the base url when launching browsers and prepended to internal urls as loaded by the browsers
* @default '/'
*/
path?: string;
/**
* Will be used as the port when launching browsers
* @default 9875
*/
port?: number;
/**
* Will be used as the hostname when launching browsers
* @default 'localhost'
*/
hostname?: string;
/**
* Will be used as the protocol when launching browsers
* @default 'http'
*/
protocol?: string;
}
// description of inline plugins
export type PluginName = string;
// tslint:disable-next-line:ban-types support for constructor function and classes
export type ConstructorFn = Function | (new (...params: any[]) => any);
export type FactoryFn = (...params: any[]) => any;
export type ConstructorFnType = ['type', ConstructorFn];
export type FactoryFnType = ['factory', FactoryFn];
export type ValueType = ['value', any];
export type InlinePluginType = FactoryFnType | ConstructorFnType | ValueType;
export type InlinePluginDef = Record<PluginName, InlinePluginType>;
export interface ConfigOptions {
/**
* @description Enable or disable watching files and executing the tests whenever one of these files changes.
* @default true
*/
autoWatch?: boolean;
/**
* @description When Karma is watching the files for changes, it tries to batch multiple changes into a single run
* so that the test runner doesn't try to start and restart running tests more than it should.
* The configuration setting tells Karma how long to wait (in milliseconds) after any changes have occurred
* before starting the test process again.
* @default 250
*/
autoWatchBatchDelay?: number;
/**
* @default ''
* @description The root path location that will be used to resolve all relative paths defined in <code>files</code> and <code>exclude</code>.
* If the basePath configuration is a relative path then it will be resolved to
* the <code>__dirname</code> of the configuration file.
*/
basePath?: string;
/**
* Configure how the browser console is logged with the following properties, all of which are optional
*/
browserConsoleLogOptions?: BrowserConsoleLogOptions;
/**
* @default 2000
* @description How long does Karma wait for a browser to reconnect (in ms).
* <p>
* With a flaky connection it is pretty common that the browser disconnects,
* but the actual test execution is still running without any problems. Karma does not treat a disconnection
* as immediate failure and will wait <code>browserDisconnectTimeout</code> (ms).
* If the browser reconnects during that time, everything is fine.
* </p>
*/
browserDisconnectTimeout?: number;
/**
* @default 0
* @description The number of disconnections tolerated.
* <p>
* The <code>disconnectTolerance</code> value represents the maximum number of tries a browser will attempt
* in the case of a disconnection. Usually any disconnection is considered a failure,
* but this option allows you to define a tolerance level when there is a flaky network link between
* the Karma server and the browsers.
* </p>
*/
browserDisconnectTolerance?: number;
/**
* @default 10000
* @description How long will Karma wait for a message from a browser before disconnecting from it (in ms).
* <p>
* If, during test execution, Karma does not receive any message from a browser within
* <code>browserNoActivityTimeout</code> (ms), it will disconnect from the browser
* </p>
*/
browserNoActivityTimeout?: number;
/**
* Timeout for the client socket connection (in ms)
* @default 20000
*/
browserSocketTimeout?: number;
/**
* @default []
* Possible Values:
* <ul>
* <li>Chrome (launcher comes installed with Karma)</li>
* <li>ChromeCanary (launcher comes installed with Karma)</li>
* <li>PhantomJS (launcher comes installed with Karma)</li>
* <li>Firefox (launcher requires karma-firefox-launcher plugin)</li>
* <li>Opera (launcher requires karma-opera-launcher plugin)</li>
* <li>Internet Explorer (launcher requires karma-ie-launcher plugin)</li>
* <li>Safari (launcher requires karma-safari-launcher plugin)</li>
* </ul>
* @description A list of browsers to launch and capture. When Karma starts up, it will also start up each browser
* which is placed within this setting. Once Karma is shut down, it will shut down these browsers as well.
* You can capture any browser manually by opening the browser and visiting the URL where
* the Karma web server is listening (by default it is <code>http://localhost:9876/</code>).
*/
browsers?: Array<AutomatedBrowsers | string>;
/**
* @default 60000
* @description Timeout for capturing a browser (in ms).
* <p>
* The <code>captureTimeout</code> value represents the maximum boot-up time allowed for a
* browser to start and connect to Karma. If any browser does not get captured within the timeout, Karma
* will kill it and try to launch it again and, after three attempts to capture it, Karma will give up.
* </p>
*/
captureTimeout?: number;
client?: ClientOptions;
/**
* @default true
* @description Enable or disable colors in the output (reporters and logs).
*/
colors?: boolean;
/**
* @default 'Infinity'
* @description How many browsers Karma launches in parallel.
* Especially on services like SauceLabs and Browserstack, it makes sense only to launch a limited
* amount of browsers at once, and only start more when those have finished. Using this configuration,
* you can specify how many browsers should be running at once at any given point in time.
*/
concurrency?: number;
/**
* When true, this will append the crossorigin attribute to generated script tags,
* which enables better error reporting for JavaScript files served from a different origin
* @default true
*/
crossOriginAttribute?: boolean;
/**
* If null (default), uses karma's own context.html file.
* @default undefined
*/
customContextFile?: string;
/**
* If null (default), uses karma's own client_with_context.html file (which is used when client.runInParent set to true).
* @default undefined
*/
customClientContextFile?: string;
/**
* If null (default), uses karma's own debug.html file.
* @default undefined
*/
customDebugFile?: string;
/**
* Custom HTTP headers that will be set upon serving files by Karma's web server.
* Custom headers are useful, especially with upcoming browser features like Service Workers.
* @default undefined
*/
customHeaders?: CustomHeaders[];
customLaunchers?: { [key: string]: CustomLauncher };
/**
* When true, this will start the karma server in another process, writing no output to the console.
* The server can be stopped using the karma stop command.
* @default false
*/
detached?: boolean;
/**
* @default []
* @description List of files/patterns to exclude from loaded files.
*/
exclude?: string[];
/**
* Enable or disable failure on running empty test-suites.
* If disabled the program will return exit-code 0 and display a warning.
* @default true
*/
failOnEmptyTestSuite?: boolean;
/**
* Enable or disable failure on tests deliberately disabled, eg fit() or xit() tests in jasmine.
* Use this to prevent accidental disabling tests needed to validate production.
* @default true
*/
failOnSkippedTests?: boolean;
/**
* Enable or disable failure on failing tests.
* @default true
*/
failOnFailingTestSuite?: boolean;
/**
* @default []
* @description List of files/patterns to load in the browser.
*/
files?: Array<FilePattern | string>;
/**
* Force socket.io to use JSONP polling instead of XHR polling
* @default false
*/
forceJSONP?: boolean;
/**
* A new error message line
* @default undefined
*/
formatError?: (msg: string) => string;
/**
* @default []
* @description List of test frameworks you want to use. Typically, you will set this to ['jasmine'], ['mocha'] or ['qunit']...
* Please note just about all frameworks in Karma require an additional plugin/framework library to be installed (via NPM).
*/
frameworks?: string[];
/**
* @default 'localhost'
* @description Hostname to be used when capturing browsers.
*/
hostname?: string;
/**
* Module used for Karma webserver
* @default undefined
*/
httpModule?: string;
/**
* @default {}
* @description Options object to be used by Node's https class.
* Object description can be found in the
* [NodeJS.org API docs](https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener)
*/
httpsServerOptions?: https.ServerOptions;
/**
* Address that the server will listen on. Change to 'localhost' to only listen to the loopback, or '::' to listen on all IPv6 interfaces
* @default '0.0.0.0' or `LISTEN_ADDR`
*/
listenAddress?: string;
/**
* @default config.LOG_INFO
* Possible values:
* <ul>
* <li>config.LOG_DISABLE</li>
* <li>config.LOG_ERROR</li>
* <li>config.LOG_WARN</li>
* <li>config.LOG_INFO</li>
* <li>config.LOG_DEBUG</li>
* </ul>
* @description Level of logging.
*/
logLevel?: string;
/**
* @default [{type: 'console'}]
* @description A list of log appenders to be used. See the documentation for [log4js] for more information.
*/
loggers?: { [name: string]: Appender } | Appender[];
/**
* @default []
* @description List of names of additional middleware you want the
* Karma server to use. Middleware will be used in the order listed.
* You must have installed the middleware via a plugin/framework
* (either inline or via NPM). Additional information can be found in
* [plugins](http://karma-runner.github.io/2.0/config/plugins.html).
* The plugin must provide an express/connect middleware function
* (details about this can be found in the
* [Express](http://expressjs.com/guide/using-middleware.html) docs).
*/
middleware?: string[];
/**
* This is the same as middleware except that these middleware will be run before karma's own middleware.
* @default []
*/
beforeMiddleware?: string[];
/**
* @default {}
* @description Redefine default mapping from file extensions to MIME-type.
* Set property name to required MIME, provide Array of extensions (without dots) as it's value.
*/
mime?: { [type: string]: string[] };
/**
* Socket.io pingTimeout in ms, https://socket.io/docs/server-api/#new-Server-httpServer-options.
* Very slow networks may need values up to 60000. Larger values delay discovery of deadlock in tests or browser crashes.
* @default 5000
*/
pingTimeout?: number;
/**
* @default ['karma-*']
* @description List of plugins to load. A plugin can be a string (in which case it will be required
* by Karma) or an inlined plugin - Object.
* By default, Karma loads all sibling NPM modules which have a name starting with karma-*.
* Note: Just about all plugins in Karma require an additional library to be installed (via NPM).
*/
plugins?: Array<PluginName | InlinePluginDef>;
/**
* @default 9876
* @description The port where the web server will be listening.
*/
port?: number;
/**
* How long will Karma wait for browser process to terminate before sending a SIGKILL signal
* @default 2000
*/
processKillTimeout?: number;
/**
* @default {'**\/*.coffee': 'coffee'}
* @description A map of preprocessors to use.
*
* Preprocessors can be loaded through [plugins].
*
* Note: Just about all preprocessors in Karma (other than CoffeeScript and some other defaults)
* require an additional library to be installed (via NPM).
*
* Be aware that preprocessors may be transforming the files and file types that are available at run time. For instance,
* if you are using the "coverage" preprocessor on your source files, if you then attempt to interactively debug
* your tests, you'll discover that your expected source code is completely changed from what you expected. Because
* of that, you'll want to engineer this so that your automated builds use the coverage entry in the "reporters" list,
* but your interactive debugging does not.
*
*/
preprocessors?: { [name: string]: string | string[] };
/**
* @default 'http:'
* Possible Values:
* <ul>
* <li>http:</li>
* <li>https:</li>
* </ul>
* @description Protocol used for running the Karma webserver.
* Determines the use of the Node http or https class.
* Note: Using <code>'https:'</code> requires you to specify <code>httpsServerOptions</code>.
*/
protocol?: string;
/**
* @default {}
* @description A map of path-proxy pairs
* The proxy can be specified directly by the target url or path, or with an object to configure more options
*/
proxies?: PathProxyPairs;
/**
* Called when requesting Proxy
* @default undefined
*/
proxyReq?: (proxyReq: any, req: any, res: any, options: object) => void;
/**
* Called when respnsing Proxy
* @default undefined
*/
proxyRes?: (proxyRes: any, req: any, res: any) => void;
/**
* @default true
* @description Whether or not Karma or any browsers should raise an error when an inavlid SSL certificate is found.
*/
proxyValidateSSL?: boolean;
/**
* @default 0
* @description Karma will report all the tests that are slower than given time limit (in ms).
* This is disabled by default (since the default value is 0).
*/
reportSlowerThan?: number;
/**
* @default ['progress']
* Possible Values:
* <ul>
* <li>dots</li>
* <li>progress</li>
* </ul>
* @description A list of reporters to use.
* Additional reporters, such as growl, junit, teamcity or coverage can be loaded through plugins.
* Note: Just about all additional reporters in Karma (other than progress) require an additional library to be installed (via NPM).
*/
reporters?: string[];
/**
* When Karma is watching the files for changes, it will delay a new run
* until the current run is finished. Enabling this setting
* will cancel the current run and start a new run immediately when a change is detected.
*/
restartOnFileChange?: boolean;
/**
* When a browser crashes, karma will try to relaunch. This defines how many times karma should relaunch a browser before giving up.
* @default 2
*/
retryLimit?: number;
/**
* @default false
* @description Continuous Integration mode.
* If true, Karma will start and capture all configured browsers, run tests and then exit with an exit code of 0 or 1 depending
* on whether all tests passed or any tests failed.
*/
singleRun?: boolean;
/**
* @default ['polling', 'websocket']
* @description An array of allowed transport methods between the browser and testing server. This configuration setting
* is handed off to [socket.io](http://socket.io/) (which manages the communication
* between browsers and the testing server).
*/
transports?: string[];
/**
* For use when the Karma server needs to be run behind a proxy that changes the base url, etc
*/
upstreamProxy?: UpstreamProxy;
/**
* @default '/'
* @description The base url, where Karma runs.
* All of Karma's urls get prefixed with the urlRoot. This is helpful when using proxies, as
* sometimes you might want to proxy a url that is already taken by Karma.
*/
urlRoot?: string;
}
export interface ClientOptions {
/**
* @default undefined
* @description When karma run is passed additional arguments on the command-line, they
* are passed through to the test adapter as karma.config.args (an array of strings).
* The client.args option allows you to set this value for actions other than run.
* How this value is used is up to your test adapter - you should check your adapter's
* documentation to see how (and if) it uses this value.
*/
args?: string[];
/**
* @default false
* @description Set style display none on client elements.
* If true, Karma does not display the banner and browser list.
* Useful when using karma on component tests with screenshots
*/
clientDisplayNone?: boolean;
/**
* @default true
* @description Run the tests inside an iFrame or a new window
* If true, Karma runs the tests inside an iFrame. If false, Karma runs the tests in a new window. Some tests may not run in an
* iFrame and may need a new window to run.
*/
useIframe?: boolean;
/**
* @default true
* @description Capture all console output and pipe it to the terminal.
*/
captureConsole?: boolean;
/**
* @default false
* @description Run the tests on the same window as the client, without using iframe or a new window
*/
runInParent?: boolean;
/**
* @default true
* @description Clear the context window
* If true, Karma clears the context window upon the completion of running the tests.
* If false, Karma does not clear the context window upon the completion of running the tests.
* Setting this to false is useful when embedding a Jasmine Spec Runner Template.
*/
clearContext?: boolean;
}
/** type to use when including a file */
export type FilePatternTypes = 'css' | 'html' | 'js' | 'dart' | 'module' | 'dom';
export interface FilePattern {
/**
* The pattern to use for matching.
*/
pattern: string;
/**
* @default true
* @description If <code>autoWatch</code> is true all files that have set watched to true will be watched
* for changes.
*/
watched?: boolean;
/**
* @default true
* @description Should the files be included in the browser using <script> tag? Use false if you want to
* load them manually, eg. using Require.js.
*/
included?: boolean;
/**
* @default true
* @description Should the files be served by Karma's webserver?
*/
served?: boolean;
/**
* Choose the type to use when including a file
* @default 'js'
* @description The type determines the mechanism for including the file.
* The css and html types create link elements; the js, dart, and module elements create script elements.
* The dom type includes the file content in the page, used, for example, to test components combining HTML and JS.
*/
type?: FilePatternTypes;
/**
* @default false
* @description Should the files be served from disk on each request by Karma's webserver?
*/
nocache?: boolean;
}
export interface CustomLauncher {
base: string;
browserName?: string;
flags?: string[];
platform?: string;
}
export interface BrowserConsoleLogOptions {
/** the desired log-level, where level log always is logged */
level?: 'log' | 'error' | 'warn' | 'info' | 'debug';
/**
* The format is a string where `%b`, `%t`, `%T`, and `%m` are replaced with the browser string,
* log type in lower-case, log type in uppercase, and log message, respectively.
* This format will only effect the output file
*/
format?: string;
/** output-path of the output-file */
path?: string;
/** if the log should be written in the terminal, or not */
terminal?: boolean;
}
export namespace config {
function parseConfig(configFilePath: string, cliOptions: ConfigOptions): Config;
}