Merge pull request #1825 from ernsheong/custom-html-setup

feat(config): Allow custom context and debug files

docs/config/01-configuration-file.md

@@ -222,7 +222,23 @@ upon  the completion of running the tests. Setting this to false is useful when
 
 **Description:** How many browser Karma launches in parallel.
 
-Especially on sevices like SauceLabs and Browserstack it makes sense to only launch a limited amount of browsers at once, and only start more when those have finished. Using this configuration you can sepcify how many browsers should be running at once at any given point in time.
+Especially on services like SauceLabs and Browserstack it makes sense to only 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.
+
+
+## customContextFile
+**Type:** string
+
+**Default:** `null`
+
+**Description:** If `null` (default), uses karma's own `context.html` file.
+
+
+## customDebugFile
+**Type:** string
+
+**Default:** `null`
+
+**Description:** If `null` (default), uses karma's own `debug.html` file.
 
 
 ## customHeaders

lib/config.js

@@ -109,11 +109,15 @@ var normalizeConfig = function (config, configFilePath) {
 
   config.files = config.files.map(createPatternObject).map(createPatternMapper(basePathResolve))
   config.exclude = config.exclude.map(basePathResolve)
+  config.customContextFile = config.customContextFile && basePathResolve(config.customContextFile)
+  config.customDebugFile = config.customDebugFile && basePathResolve(config.customDebugFile)
 
   // normalize paths on windows
   config.basePath = helper.normalizeWinPath(config.basePath)
   config.files = config.files.map(createPatternMapper(helper.normalizeWinPath))
   config.exclude = config.exclude.map(helper.normalizeWinPath)
+  config.customContextFile = helper.normalizeWinPath(config.customContextFile)
+  config.customDebugFile = helper.normalizeWinPath(config.customDebugFile)
 
   // normalize urlRoot
   config.urlRoot = normalizeUrlRoot(config.urlRoot)
@@ -235,6 +239,8 @@ var Config = function () {
   this.httpsServerConfig = {}
   this.basePath = ''
   this.files = []
+  this.customContextFile = null
+  this.customDebugFile = null
   this.exclude = []
   this.logLevel = constant.LOG_INFO
   this.colors = true

lib/middleware/karma.js

@@ -59,8 +59,9 @@ var getXUACompatibleUrl = function (url) {
   return value
 }
 
-var createKarmaMiddleware = function (filesPromise, serveStaticFile,
-  /* config.basePath */ basePath, /* config.urlRoot */ urlRoot, /* config.client */ client) {
+var createKarmaMiddleware = function (filesPromise, serveStaticFile, serveFile,
+  /* config.basePath */ basePath, /* config.urlRoot */ urlRoot, /* config.client */ client,
+  /* config.customContextFile */ customContextFile, /* config.customDebugFile */ customDebugFile) {
   return function (request, response, next) {
     var requestUrl = request.normalizedUrl.replace(/\?.*/, '')
 
@@ -103,9 +104,24 @@ var createKarmaMiddleware = function (filesPromise, serveStaticFile,
 
     // serve context.html - execution context within the iframe
     // or debug.html - execution context without channel to the server
-    if (requestUrl === '/context.html' || requestUrl === '/debug.html') {
+    var isRequestingContextFile = requestUrl === '/context.html'
+    var isRequestingDebugFile = requestUrl === '/debug.html'
+    if (isRequestingContextFile || isRequestingDebugFile) {
       return filesPromise.then(function (files) {
-        serveStaticFile(requestUrl, response, function (data) {
+        var fileServer
+        var requestedFileUrl
+        if (isRequestingContextFile && customContextFile) {
+          fileServer = serveFile
+          requestedFileUrl = customContextFile
+        } else if (isRequestingDebugFile && customDebugFile) {
+          fileServer = serveFile
+          requestedFileUrl = customDebugFile
+        } else {
+          fileServer = serveStaticFile
+          requestedFileUrl = requestUrl
+        }
+
+        fileServer(requestedFileUrl, response, function (data) {
           common.setNoCacheHeaders(response)
 
           var scriptTags = files.included.map(function (file) {
@@ -178,8 +194,9 @@ var createKarmaMiddleware = function (filesPromise, serveStaticFile,
   }
 }
 
-createKarmaMiddleware.$inject = ['filesPromise', 'serveStaticFile',
-  'config.basePath', 'config.urlRoot', 'config.client']
+createKarmaMiddleware.$inject = ['filesPromise', 'serveStaticFile', 'serveFile',
+  'config.basePath', 'config.urlRoot', 'config.client', 'config.customContextFile',
+  'config.customDebugFile']
 
 // PUBLIC API
 exports.create = createKarmaMiddleware

test/e2e/custom-context.feature

@@ -0,0 +1,22 @@
+Feature: Custom Context File
+  In order to use Karma
+  As a person who wants to write great tests
+  I want Karma to use a custom context file
+
+  Scenario: Custom context.html file
+    Given a configuration with:
+      """
+      files = ['context/*.js'];
+      browsers = ['PhantomJS'];
+      plugins = [
+        'karma-jasmine',
+        'karma-phantomjs-launcher'
+      ];
+      customContextFile = 'context/context2.html'
+      """
+    When I start Karma
+    Then it passes with:
+      """
+      .
+      PhantomJS
+      """

test/e2e/steps/core_steps.js

@@ -154,7 +154,7 @@ module.exports = function coreSteps () {
       return callback()
     }
 
-    if (actualOutput.indexOf(expectedOutput) === 0) {
+    if (actualOutput.indexOf(expectedOutput) >= 0) {
       return callback()
     }
 

test/e2e/support/context/context2.html

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<!--
+This is the execution context.
+Loaded within the iframe.
+Reloaded before every execution run.
+-->
+<html>
+<head>
+  <title></title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />
+</head>
+<body>
+  <!-- The scripts need to be in the body DOM element, as some test running frameworks need the body
+       to have already been created so they can insert their magic into it. For example, if loaded
+       before body, Angular Scenario test framework fails to find the body and crashes and burns in
+       an epic manner. -->
+  <div id="custom-context"></div>
+  <script type="text/javascript">
+    // sets window.__karma__ and overrides console and error handling
+    // Use window.opener if this was opened by someone else - in a new window
+    if (window.opener) {
+      window.opener.karma.setupContext(window);
+    } else {
+      window.parent.karma.setupContext(window);
+    }
+
+    // All served files with the latest timestamps
+    %MAPPINGS%
+  </script>
+  <!-- Dynamically replaced with <script> tags -->
+  %SCRIPTS%
+  <script type="text/javascript">
+    window.__karma__.loaded();
+  </script>
+</body>
+</html>

test/e2e/support/context/test.js

@@ -0,0 +1,5 @@
+describe('custom context file', function () {
+  it('should be able to find custom DOM elements', function () {
+    expect(document.querySelector('#custom-context') == null).toBe(false)
+  })
+})

test/unit/config.spec.js

@@ -261,7 +261,9 @@ describe('config', () => {
     it('should convert patterns to objects and set defaults', () => {
       var config = normalizeConfigWithDefaults({
         basePath: '/base',
-        files: ['a/*.js', {pattern: 'b.js', watched: false, included: false}, {pattern: 'c.js'}]
+        files: ['a/*.js', {pattern: 'b.js', watched: false, included: false}, {pattern: 'c.js'}],
+        customContextFile: 'context.html',
+        customDebugFile: 'debug.html'
       })
 
       expect(config.files.length).to.equal(3)
@@ -283,6 +285,9 @@ describe('config', () => {
       expect(file.included).to.equal(true)
       expect(file.served).to.equal(true)
       expect(file.watched).to.equal(true)
+
+      expect(config.customContextFile).to.equal(resolveWinPath('/base/context.html'))
+      expect(config.customDebugFile).to.equal(resolveWinPath('/base/debug.html'))
     })
 
     it('should normalize preprocessors to an array', () => {

test/unit/middleware/karma.spec.js

@@ -40,7 +40,7 @@ describe('middleware.karma', () => {
     response = new HttpResponseMock()
     filesDeferred = helper.defer()
     serveFile = createServeFile(fsMock, '/karma/static')
-    handler = createKarmaMiddleware(filesDeferred.promise, serveFile, '/base/path', '/__karma__/', clientConfig)
+    handler = createKarmaMiddleware(filesDeferred.promise, serveFile, null, '/base/path', '/__karma__/', clientConfig)
   })
 
   // helpers
@@ -92,7 +92,7 @@ describe('middleware.karma', () => {
   })
 
   it('should serve client.html', (done) => {
-    handler = createKarmaMiddleware(null, serveFile, '/base', '/')
+    handler = createKarmaMiddleware(null, serveFile, null, '/base', '/')
 
     response.once('end', () => {
       expect(nextSpy).not.to.have.been.called
@@ -104,7 +104,7 @@ describe('middleware.karma', () => {
   })
 
   it('should serve /?id=xxx', (done) => {
-    handler = createKarmaMiddleware(null, serveFile, '/base', '/')
+    handler = createKarmaMiddleware(null, serveFile, null, '/base', '/')
 
     response.once('end', () => {
       expect(nextSpy).not.to.have.been.called
@@ -116,7 +116,7 @@ describe('middleware.karma', () => {
   })
 
   it('should serve /?x-ua-compatible with replaced values', (done) => {
-    handler = createKarmaMiddleware(null, serveFile, '/base', '/')
+    handler = createKarmaMiddleware(null, serveFile, null, '/base', '/')
 
     response.once('end', () => {
       expect(nextSpy).not.to.have.been.called