CHANGELOG.md

@@ -1,3 +1,31 @@
+<a name="3.1.0"></a>
+# [3.1.0](https://github.com/karma-runner/karma/compare/v3.0.0...v3.1.0) (2018-10-22)
+
+
+### Bug Fixes
+
+* work around broken console methods ([873e4f9](https://github.com/karma-runner/karma/commit/873e4f9)), closes [/github.com/angular/angular.js/pull/16644#issuecomment-407680658](https://github.com//github.com/angular/angular.js/pull/16644/issues/issuecomment-407680658)
+* **browser:** emit 'browsers_change' in collection ([#3183](https://github.com/karma-runner/karma/issues/3183)) ([7634e71](https://github.com/karma-runner/karma/commit/7634e71))
+* **config:** remove phantomjs in favor of chrome headless ([#3175](https://github.com/karma-runner/karma/issues/3175)) ([0f8b2b1](https://github.com/karma-runner/karma/commit/0f8b2b1))
+* **init:** Support ChromeHeadless in `validateBrowser` ([#3110](https://github.com/karma-runner/karma/issues/3110)) ([eeadcf2](https://github.com/karma-runner/karma/commit/eeadcf2))
+* **middleware:** simplify stripHost. ([#3115](https://github.com/karma-runner/karma/issues/3115)) ([d65e911](https://github.com/karma-runner/karma/commit/d65e911))
+* **runner:** Do not persist grep option across runs ([#3121](https://github.com/karma-runner/karma/issues/3121)) ([c91cb81](https://github.com/karma-runner/karma/commit/c91cb81))
+* **runner:** Make exit code configurable when tests are failing ([#3116](https://github.com/karma-runner/karma/issues/3116)) ([74da748](https://github.com/karma-runner/karma/commit/74da748)), closes [#1300](https://github.com/karma-runner/karma/issues/1300)
+* **test/client:** revert const/let changes. ([c097ecf](https://github.com/karma-runner/karma/commit/c097ecf))
+
+
+### Features
+
+* **config:** Add config option for browser socket timeout ([#3102](https://github.com/karma-runner/karma/issues/3102)) ([11e3a9d](https://github.com/karma-runner/karma/commit/11e3a9d)), closes [#2927](https://github.com/karma-runner/karma/issues/2927)
+* **config:** add support for ES modules ([e811adb](https://github.com/karma-runner/karma/commit/e811adb))
+* **frameworks:** report start() errors back to server. ([#3126](https://github.com/karma-runner/karma/issues/3126)) ([8257375](https://github.com/karma-runner/karma/commit/8257375))
+* **server:** .dom files include HTML tags in page. ([#3178](https://github.com/karma-runner/karma/issues/3178)) ([4651524](https://github.com/karma-runner/karma/commit/4651524))
+* **server:** Add public API to force a file refresh ([dab8a82](https://github.com/karma-runner/karma/commit/dab8a82))
+* **server:** Add stop method ([#3153](https://github.com/karma-runner/karma/issues/3153)) ([6d96d8e](https://github.com/karma-runner/karma/commit/6d96d8e)), closes [#3149](https://github.com/karma-runner/karma/issues/3149)
+* **server:** Add support for encoded source files ([#3123](https://github.com/karma-runner/karma/issues/3123)) ([68b37d3](https://github.com/karma-runner/karma/commit/68b37d3))
+
+
+
 <a name="3.0.0"></a>
 # [3.0.0](https://github.com/karma-runner/karma/compare/v2.0.5...v3.0.0) (2018-08-09)
 
@@ -13,6 +41,10 @@
 * **travis:** validate TRAVIS_COMMIT if TRAVIS_PULL_REQUEST_SHA is not set. ([#3094](https://github.com/karma-runner/karma/issues/3094)) ([fba5d36](https://github.com/karma-runner/karma/commit/fba5d36))
 * **travis:** Validate TRAVIS_PULL_REQUEST_SHA rather than TRAVIS_COMMIT. ([#3093](https://github.com/karma-runner/karma/issues/3093)) ([a58fa45](https://github.com/karma-runner/karma/commit/a58fa45))
 
+### BREAKING CHANGES
+
+* Drop Support for Nodejs4 ([#3082](https://github.com/karma-runner/karma/pull/3082))
+
 
 
 <a name="2.0.6"></a>

CONTRIBUTING.md

@@ -18,7 +18,7 @@ with a fix.
 **Working on your first Pull Request?** You can learn how from this *free* series
 [How to Contribute to an Open Source Project on GitHub][egghead_series]
 
-[docs_contributing]: http://karma-runner.github.io/0.13/dev/contributing.html
+[docs_contributing]: http://karma-runner.github.io/latest/dev/contributing.html
 [gitter]: https://gitter.im/karma-runner/karma
 [stackoverflow]: http://stackoverflow.com/questions/tagged/karma-runner
 [github_newissue]: https://github.com/karma-runner/karma/issues/new

LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (C) 2011-2016 Google, Inc.
+Copyright (C) 2011-2018 Google, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,3 @@
+Check that your description matches the automatic change-log format:
+http://karma-runner.github.io/latest/dev/git-commit-msg.html
+then delete this reminder.

client/constants.js

@@ -2,5 +2,6 @@ module.exports = {
   VERSION: '%KARMA_VERSION%',
   KARMA_URL_ROOT: '%KARMA_URL_ROOT%',
   KARMA_PROXY_PATH: '%KARMA_PROXY_PATH%',
+  BROWSER_SOCKET_TIMEOUT: '%BROWSER_SOCKET_TIMEOUT%',
   CONTEXT_URL: 'context.html'
 }

client/main.js

@@ -9,12 +9,13 @@ var constants = require('./constants')
 
 var KARMA_URL_ROOT = constants.KARMA_URL_ROOT
 var KARMA_PROXY_PATH = constants.KARMA_PROXY_PATH
+var BROWSER_SOCKET_TIMEOUT = constants.BROWSER_SOCKET_TIMEOUT
 
 // Connect to the server using socket.io http://socket.io
 var socket = io(location.host, {
   reconnectionDelay: 500,
   reconnectionDelayMax: Infinity,
-  timeout: 20000,
+  timeout: BROWSER_SOCKET_TIMEOUT,
   path: KARMA_PROXY_PATH + KARMA_URL_ROOT.substr(1) + 'socket.io',
   'sync disconnect on unload': true
 })

context/karma.js

@@ -37,7 +37,11 @@ function ContextKarma (callParentKarmaMethod) {
   this.loaded = function () {
     // has error -> cancel
     if (!hasError) {
-      this.start(this.config)
+      try {
+        this.start(this.config)
+      } catch (error) {
+        this.error(error.stack || error.toString())
+      }
     }
 
     // remove reference to child iframe
@@ -118,7 +122,11 @@ function ContextKarma (callParentKarmaMethod) {
         }
         localConsole[method] = function () {
           self.log(method, arguments)
-          return Function.prototype.apply.call(orig, localConsole, arguments)
+          try {
+            return Function.prototype.apply.call(orig, localConsole, arguments)
+          } catch (error) {
+            self.log('warn', ['Console method ' + method + ' threw: ' + error])
+          }
         }
       }
       for (var i = 0; i < logMethods.length; i++) {

docs/config/01-configuration-file.md

@@ -53,6 +53,20 @@ module.exports = (config) => {
 }
 ```
 
+### Customized TypeScript Configuration
+Under the hood Karma uses ts-node to transpile TypeScript to JavaScript. If the resolved `tsconfig.json` has `module` configured as `ES` formats. You might get errors like `SyntaxError: Unexpected token`. This is due that in Node `ES` module formats are not supported. To overcome this issue you need to configure ts-node to use `commonjs` module format.
+
+Create a JavaScript configuration file that overrides the module format.
+```javascript
+// karma.conf.js
+require('ts-node').register({ 
+  compilerOptions: { 
+    module: 'commonjs' 
+  } 
+});
+require('./karma.conf.ts');
+```
+
 ## File Patterns
 All of the configuration options, which specify file paths, use the [minimatch][minimatch] library to facilitate flexible
 but concise file expressions so you can easily list all of the files you want to include and exclude.
@@ -793,6 +807,29 @@ If set then the following fields will be defined and can be overriden:
 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.
 
+## browserSocketTimeout
+**Type:** Number
+
+**Default:** `20000`
+
+**Description:** Timeout for the client socket connection (in ms).
+
+This configuration represents the amount of time that the client will wait for the socket
+to connect.
+
+When running a browser in different environments, it can take different amounts of time for the
+client socket to connect. If Karma cannot connect within the default timeout, you may see an
+error similar to the following:
+```
+ChromeHeadless have not captured in 60000ms, killing.
+Trying to start ChromeHeadless again (1/2).
+ChromeHeadless have not captured in 60000ms, killing.
+Trying to start ChromeHeadless again (2/2).
+ChromeHeadless have not captured in 60000ms, killing.
+ChromeHeadless failed 2 times(timeout). Giving up.
+```
+If you see this error, you can try increasing the socket connection timeout.
+
 
 [plugins]: plugins.html
 [config/files]: files.html

docs/config/02-files.md

@@ -34,6 +34,10 @@ Each pattern is either a simple string or an object with the following propertie
   * `js`
   * `dart`
   * `module`
+  * `dom`
+* **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 combinging HTML and JS.
 
 ### `watched`
 * **Type.** Boolean
@@ -46,17 +50,17 @@ Each pattern is either a simple string or an object with the following propertie
 * **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](../plus/requirejs.html).
-    
+
     If a file is covered by multiple patterns with different `include` properties, the most specific pattern takes
     precedence over the other.
-    
-    The specificity of the pattern is defined as a six-tuple, where larger tuple implies lesser specificity: 
+
+    The specificity of the pattern is defined as a six-tuple, where larger tuple implies lesser specificity:
     *(n<sub>glob parts</sub>, n<sub>glob star</sub>, n<sub>star</sub>, n<sub>ext glob</sub>, n<sub>range</sub>, n<sub>optional</sub>)*.
-    Tuples are compared lexicographically. 
-    
-    The *n<sub>glob parts</sub>* is the number of patterns after the bracket sections are expanded. E.g. the 
+    Tuples are compared lexicographically.
+
+    The *n<sub>glob parts</sub>* is the number of patterns after the bracket sections are expanded. E.g. the
     the pattern *{0...9}* will yield *n<sub>glob parts</sub>=10*. The rest of the tuple is decided as the least
-    specific of each expanded pattern. 
+    specific of each expanded pattern.
 
 ### `served`
 * **Type.** Boolean

docs/dev/04-public-api.md

@@ -33,6 +33,14 @@ Trigger a file list refresh. Returns a promise.
 server.refreshFiles()
 ```
 
+### **server.refreshFile(path)**
+
+Trigger a file refresh. Returns a promise.
+
+```javascript
+server.refreshFile('src/js/module-dep.js')
+```
+
 ### Events
 
 The `server` object is an [`EventEmitter`](https://nodejs.org/docs/latest/api/events.html#events_class_events_eventemitter). You can simply listen to events like this:

docs/dev/05-plugins.md

@@ -18,6 +18,17 @@ Karma can be extended through plugins. A plugin is essentially an NPM module. Ty
 - use NPM keywords `karma-plugin`, `karma-launcher`
 
 ## Preprocessors
+
+A preprocessor is a function that accepts three arguments (`content`, `file`, and `next`), mutates the content in some way, and passes it on to the next preprocessor.
+
+- arguments passed to preprocessor plugins:
+  - **`content`** of the file being processed
+  - **`file`** object describing the file being processed
+     - **path:** the current file, mutable file path. e. g. `some/file.coffee` -> `some/file.coffee.js` _This path is mutable and may not actually exist._
+     - **originalPath:** the original, unmutated path
+     - **encodings:** A mutable, keyed object where the keys are a valid encoding type ('gzip', 'compress', 'br', etc.) and the values are the encoded content. Encoded content should be stored here and not resolved using `next(null, encodedContent)`
+     - **type:** the pattern used to match the file
+  - **`next`** function to be called when preprocessing is complete, should be called as `next(null, processedContent)` or `next(error)`
 - example plugins: [karma-coffee-preprocessor], [karma-ng-html2js-preprocessor]
 - use naming convention is `karma-*-preprocessor`
 - user NPM keywords `karma-plugin`, `karma-preprocessor`

docs/intro/01-installation.md

@@ -5,7 +5,7 @@ Karma runs on [Node.js] and is available as an [NPM] package.
 On Mac or Linux we recommend using [NVM](https://github.com/creationix/nvm). On Windows, download Node.js
 from [the official site](https://nodejs.org/) or use the [NVM PowerShell Module](https://www.powershellgallery.com/packages/nvm).
 
-Note: Karma currently works on Node.js **4.x**, **5.x**, **6.x**, **7.x**, and **8.x**. See [FAQ] for more info.
+Note: Karma currently works on Node.js **6.x**, **8.x**, and **10.x**. See [FAQ] for more info.
 
 ## Installing Karma and plugins
 

docs/intro/04-faq.md

@@ -25,7 +25,7 @@ The latest stable version from NPM (`npm install karma`). See [versioning] for m
 
 
 ### Which version of Node.js does Karma run with?
-Karma works on all LTS versions node in active maintenance state (see [LTS docs](https://github.com/nodejs/LTS/blob/master/README.md) for more info) as well as the latest stable version. That is **4.x**, **5.x**, **6.x**, and **8.x** at this point.
+Karma works on all LTS versions node in active maintenance state (see [LTS docs](https://github.com/nodejs/Release/blob/master/README.md) for more info) as well as the latest stable version. That is **6.x**, **8.x** and **10.x** at this point.
 
 
 [mailing list]: https://groups.google.com/d/forum/karma-users