tib

    0.7.5 • Public • Published

    test in browser (tib)

    Build Status Coverage Status npm npm (scoped with tag)

    Helper classes for e2e browser testing in Node with a uniform interface.

    Introduction

    tib aims to provide a uniform interface for testing with both jsdom, Puppeteer and Selenium while using either local browsers or a 3rd party provider. This way you can write a single e2e test and simply switch the browser environment by changing the BrowserString

    The term helper classes stems from that this package wont enforce test functionality on you (which would require another learning curve). tib allows you to use the test suite you are already familair with. Use tib to retrieve and assert whether the html you expect to be loaded is really loaded, both on page load as after interacting with it through javascript.

    Supported browsers/drivers/providers:

    • Puppeteer
      • -core
    • Selenium
      • Firefox
      • Chrome
      • Safari
      • IE (untested)
      • Edge (untested)
    • jsdom
    • BrowserStack

    All browser/provider specific dependencies are peer dependencies and are dynamically loaded. You only need to install the peer-dependencies you plan to use

    Features

    • Retrieve html as ASTElements (using 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 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

    Documentation

    Install

    $ yarn add -D tib

    Extra steps on Mac OS with Safari

    Make sure to Enable WebDriver Support, see here for more information

    Usage

    import { createBrowser } from 'tib'
    
    const browserString = 'firefox/headless'
    const autoStart = false // default true
    const config = {
      extendPage(page) {
        return {
          myPageFn() {
            // do something
          }
        }
      }
    }
    
    const browser = await createBrowser(browserString, config, autoStart)
    if (!autoStart) {
      await browser.start()
    }

    Browser Strings

    Browser strings are broken up into capability pairs (e.g. chrome 71 is a capability pair consisting of browser name and browser version). Those pairs are then matched against a list of known properties (see constants.js for the full list). Browser and provider properties are used to determine the required import (see browsers.js). The remaining properties should be capabilities and are depending on whether the value was recognised applied to the browser instance by calling the corresponding set<CapabilityName> methods.

    API

    Read the API reference

    Example

    also check our e2e tests for more information

    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(browserString, {
          // if true or undefined then Xvfb is automatically started before
          // the browser and the displayNum=99 added to the process.env
          xvfb: false,
          quiet: 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
          },
          extendPage(page) {
            return {
              getRouteData() {
                return page.runScript(() => {
                  // this function is executed within the page context
                  // if you use features like Promises and are testing on
                  // older browsers make sure you have a polyfill already
                  // loaded
                  return myRouter.currentRoute
                })
              },
              async navigate(path) {
                await page.runAsyncScript((path) => {
                  return new Promise(resolve => {
                    myRouter.on('navigationFinished', resolve)
                    window.myRouter.navigate(path)
                  })
                }, path)
              }
            }
          }
        })
      })
    
      afterAll(() => {
        if (myBrowser) {
          await myBrowser.close()
        }
      })
    
      test('router', async () => {
        const url = myBrowser.getUrl('/')
    
        const page = await myBrowser.page(url)
    
        // you should probably expect and not log this
        console.log(await page.getHtml())
        console.log(await page.getElement('div'))
        console.log(await page.getElements('div'))
        console.log(await page.getElementCount('div'))
        console.log(await page.getAttribute('div', 'id'))
        console.log(await page.getAttributes('div', 'id'))
        console.log(await page.getText('h1'))
        console.log(await page.getTexts('h1, h2'))
        console.log(await page.getTitle())
    
        await page.navigate('/about')
        console.log(await page.getRouteData())
    
        console.log(await page.getTitle())
      })
    })

    FAQ

    I receive a WebDriverError: invalid argument: can't kill an exited process error

    Its a Selenium error and means the browser couldnt be started or exited immeditately after start. Try to run with xvfb: true

    Known issues / caveats

    • If Node force exits then local running commands might keep running (eg geckodriver, chromedriver, Xvfb, browserstack-local)
      • workaround: none unfortunately
    • On CircleCI puppeteer sometimes triggers Protocol error (Runtime.callFunctionOn): Target closed error on page.evaluate. This could be related to a version mismatch between the browser and puppeteer.
      • workaround: use chrome/selenium
    • with Firefox you cannot run two page functions at the same time, also not when they are async
      • workaround: combine the functionality you need in a single page function
    • with Safari you can get ScriptTimeoutError on asynchronous page function execution. Often the timeout seems false as it is in ms and the scripts are still executed
      • workaround: wrap runAsyncScript calls in try/catch to just ignore the timeout :)

    Todo's

    • local ie/edge
    • more platforms
      • SauceLabs (key required)
      • others?
    • increase coverage

    Install

    npm i tib

    DownloadsWeekly Downloads

    69

    Version

    0.7.5

    License

    MIT

    Unpacked Size

    208 kB

    Total Files

    112

    Last publish

    Collaborators

    • avatar