feat: add static webserver command

Author: pimlie

README.md

@@ -30,12 +30,13 @@ All browser/provider specific dependencies are peer dependencies and are dynamic
 
 ## Features
 
-- retrieve html as ASTElements (using [`vue-template-compiler`](https://www.npmjs.com/package/vue-template-compiler))
+- Retrieve html as ASTElements (using [`vue-template-compiler`](https://www.npmjs.com/package/vue-template-compiler))
 - Very easy to write page function to run in the browser
   - just remember to only use language features the loaded page already has polyfills for
   - syntax is automatically transpiled when browser version is specified
     - e.g. arrow functions will be transpiled to normal functions when you specify 'safari 5.1'
-- Supports BrowserStack-Local to easily tests local code
+- Supports BrowserStack-Local to easily tests local html files
+- Serve your local html files with a simple webserver
 - Automatically starts Xvfb for non-headless support (on supported platforms)
   - set `xvfb: false` if you want to specify DISPLAY manually
 
@@ -88,21 +89,28 @@ also check [our e2e tests](./test/e2e/basic.test.js) for more information
 ```js
 import { createBrowser, commands: { Xvfb, BrowserStackLocal } } from 'tib'
 
+const browserString = 'windows 10/chrome 71/browserstack/local/1920x1080'
+// const browserString = 'puppeteer/core/staticserver'
+
 describe('my e2e test', () => {
   let myBrowser
 
   beforeAll(async () => {
-    myBrowser = await createBrowser('windows 10/chrome 71/browserstack/local/1920x1080', {
+    myBrowser = await createBrowser(browserString, {
       // if true or undefined then Xvfb is automatically started before
       // the browser and the displayNum=99 added to the process.env
       xvfb: false,
+      folder: process.cwd(),
+      staticServer: {
+        host: 'localhost', // or set process.env.HOST
+        port: 3000 // or set process.env.PORT
+      },
       // only used for BrowserStackLocal browsers
       BrowserStackLocal: {
         start: true, // default, if false then call 'const pid = await BrowserStackLocal.start()'
         stop: true,  // default, if false then call 'await BrowserStackLocal.stop(pid)'
         user: process.env.BROWSERSTACK_USER,
-        key: process.env.BROWSERSTACK_KEY,
-        folder: process.cwd()
+        key: process.env.BROWSERSTACK_KEY
       },
       extendPage(page) {
         return {
@@ -136,7 +144,7 @@ describe('my e2e test', () => {
 
   test('router', async () => {
     // note: this method is only available for browserstack/local browsers
-    const url = myBrowser.getLocalFolderUrl()
+    const url = myBrowser.getUrl()
 
     const page = await myBrowser.page(url)
 
@@ -229,9 +237,8 @@ If you use Jest for testing, you might also need to exclude `tib` from the [`tra
 
 ## TODO
 - validation
-- local ie/edge/safari
+- local ie/edge
 - more platforms, which ones?
   - SauceLabs (unable to test as I have no key)
 - screenshotting
 - increase coverage
-- ?

docs/API.md

@@ -7,6 +7,11 @@
 
 ## Configuration
 
+### `folder`
+
+The local folder with static html files you wish to test. This folder is used both by browserstack-local and the static webserver.
+If you dont use either of those, the files will be loaded through the `file://` protocol.
+
 ### `xvfb`
 _boolean_ (default: `true`)
 
@@ -26,6 +31,18 @@ This function is called after a page is opened and receives the `webpage` instan
 
 It should return or resolve to an object which is used in the [page proxy](#pageproxy)
 
+### `staticServer`
+_object_
+
+The configuration for the included static webserver.
+
+- `host` (_string_, default `localhost`)<br/>
+The hostname / ip to run the static server on. Optionally you can also set the `HOST` env variable.
+- `port` (_integer_, default `3000`)<br/>
+The port the static server should run on. Optionally you can also set the `PORT` env variable.
+- `folder` (_string_, optional)<br/>
+The path used as the webroot for the webserver. If not provided the default `folder` browser config option is used
+
 ### `BrowserStackLocal`
 _object_
 
@@ -37,14 +54,14 @@ The object can list the following properties:
 Whether to start the browserstack-local daemon on `browser.start`
 - `stop` (_boolean_, default `true`)<br/>
 Whether to stop the browserstack-local daemon on `browser.close`
-- `folder` (_string_)<br/>
-The path to the folder which should be accessible through the browserstack-local tunnel
 - `user` (_string_)<br/>
 Your browserstack user name<br/>
 > for security reasons it is recommended to use the env var `BROWSERSTACK_USER` instead
 - `key` (_string_)<br/>
 Your browserstack key<br/>
 > for security reasons it is recommended to use the env var `BROWSERSTACK_KEY` instead
+- `folder` (_string_, optional)<br/>
+The path to the folder which should be accessible through the browserstack-local tunnel. If not provided the default `folder` browser config option is used
 
 ## Browser methods
 
@@ -76,6 +93,13 @@ _resolves_ `void`
 
 Closes the browser and all commands that were started
 
+### `getUrl`
+_arguments_
+  - path (type: `string`)
+_returns_ `url`
+
+Returns the full url for a path. Depending your browser config it returns the url to/for browserstack-local, static server or just local files.
+
 ### `page`
 _arguments_
   - url (type: `string`)

package.json

@@ -62,6 +62,7 @@
     "eslint-plugin-promise": "^4.2.1",
     "eslint-plugin-standard": "^4.0.0",
     "eslint-plugin-vue": "^5.2.3",
+    "express": "^4.17.1",
     "geckodriver": "^1.16.2",
     "glob": "^7.1.4",
     "jest": "^24.8.0",
@@ -75,15 +76,18 @@
     "rollup-plugin-json": "^4.0.0",
     "rollup-plugin-node-resolve": "^5.2.0",
     "selenium-webdriver": "^4.0.0-alpha.1",
+    "serve-static": "^1.14.1",
     "standard-version": "^6.0.1",
     "yarn": "^1.17.3"
   },
   "peerDependencies": {
     "browserstack-local": "^1.4.0",
     "chromedriver": "^75.1.0",
+    "express": "^4.17.1",
     "geckodriver": "^1.16.2",
     "puppeteer": "^1.18.1",
     "puppeteer-core": "^1.18.1",
-    "selenium-webdriver": "^4.0.0-alpha.1"
+    "selenium-webdriver": "^4.0.0-alpha.1",
+    "serve-static": "^1.14.1"
   }
 }

src/browser.js

@@ -1,7 +1,8 @@
+import path from 'path'
 import Hookable from 'hable'
 import onExit from 'signal-exit'
 import BrowserError from './utils/error'
-import Xvfb from './utils/commands/xvfb'
+import { Xvfb, StaticServer } from './utils/commands'
 import { browsers } from './browsers'
 import {
   abstractGuard,
@@ -42,6 +43,11 @@ export default class Browser extends Hookable {
           continue
         }
 
+        if (key === 'staticserver') {
+          this.config.staticServer = true
+          continue
+        }
+
         if (key === 'xvfb') {
           if (this.config.browserConfig[key] === 'false' || this.config.browserConfig.headless) {
             continue
@@ -67,9 +73,8 @@ export default class Browser extends Hookable {
       this.config.xvfb = Xvfb.isSupported()
     }
 
-    if (this.config.xvfb) {
-      Xvfb.load(this)
-    }
+    Xvfb.load(this)
+    StaticServer.load(this)
 
     if (isMockedFunction(setTimeout, 'setTimeout')) {
       // eslint-disable-next-line no-console
@@ -128,6 +133,15 @@ The browser probably won't ever start with globally mocked timers. Will try to a
     await this.callHook('dependencies:loaded')
   }
 
+  getUrl(urlPath) {
+    if (this.config.staticServer) {
+      const { host, port } = this.config.staticServer
+      return `http://${host}:${port}${urlPath}`
+    }
+
+    return `file://${path.join(this.config.folder, urlPath)}`
+  }
+
   getCapabilities(capabilities) {
     if (!capabilities) {
       return this.capabilities

src/browserstack/local.js

@@ -10,6 +10,7 @@ export default class BrowserStackLocalBrowser extends BrowserStackBrowser {
       start: true,
       stop: true,
       key: this.getConfigProperty('key'),
+      folder: this.config.folder,
       ...this.config.BrowserStackLocal
     }
 
@@ -39,4 +40,8 @@ export default class BrowserStackLocalBrowser extends BrowserStackBrowser {
   getLocalFolderUrl(path = '/') {
     return `http://${this.getConfigProperty('user')}.browserstack.com${path}`
   }
+
+  getUrl(path) {
+    return this.getLocalFolderUrl(path)
+  }
 }

src/utils/commands/browserstack-local.js

@@ -18,6 +18,7 @@ export default class BrowserStackLocal {
   }
 
   static async start(config = {}) {
+    // TODO: support webserver
     if (!config.folder) {
       config.folder = path.resolve(process.cwd())
     }

src/utils/commands/index.js

@@ -1,7 +1,9 @@
 import Xvfb from './xvfb'
 import BrowserStackLocal from './browserstack-local'
+import StaticServer from './static-server'
 
 export {
   Xvfb,
-  BrowserStackLocal
+  BrowserStackLocal,
+  StaticServer
 }

src/utils/commands/static-server.js

@@ -0,0 +1,61 @@
+import { loadDependency } from '..'
+
+export default class StaticServer {
+  static async loadDependencies() {
+    if (StaticServer.express) {
+      return
+    }
+
+    StaticServer.express = await loadDependency('express')
+    StaticServer.serveStatic = await loadDependency('serve-static')
+  }
+
+  static load(browser) {
+    if (!browser.config.staticServer) {
+      return
+    }
+
+    if (browser.config.staticServer === true) {
+      const { folder } = browser.config
+      browser.config.staticServer = { folder }
+    }
+
+    if (!browser.config.staticServer.folder) {
+      return
+    }
+
+    browser.hook('start:before', () => StaticServer.start(browser.config.staticServer))
+    browser.hook('close:after', StaticServer.stop)
+  }
+
+  static async start(config) {
+    await StaticServer.loadDependencies()
+
+    const app = StaticServer.express()
+
+    app.use(StaticServer.serveStatic(config.folder))
+
+    let { host, port } = config
+    host = process.env.HOST || host || 'localhost'
+    port = process.env.PORT || port || 3000
+
+    StaticServer.server = app.listen(port, host)
+
+    // eslint-disable-next-line no-console
+    console.info(`tib: Static server started on http://${host}:${port}`)
+
+    config.host = host
+    config.port = port
+  }
+
+  static stop() {
+    if (StaticServer.server) {
+      return new Promise((resolve) => {
+        StaticServer.server.close(() => {
+          StaticServer.server = undefined
+          resolve()
+        })
+      })
+    }
+  }
+}

src/utils/commands/xvfb.js

@@ -15,6 +15,10 @@ const supportedPlatforms = [
 
 export default class Xvfb {
   static load(browser) {
+    if (!browser.config.xvfb) {
+      return
+    }
+
     Xvfb.isSupported(true)
 
     const browserConfig = browser.config.browserConfig

src/utils/constants.js

@@ -12,7 +12,8 @@ export const browsers = [
 
 export const browserOptions = [
   'headless',
-  'xvfb'
+  'xvfb',
+  'staticserver'
 ]
 
 export const drivers = [