testingbot-tunnel-launcher/README.md

A wrapper around TestingBot's Tunnel

# testingbot-tunnel-launcher

[![npm](https://img.shields.io/npm/v/testingbot-tunnel-launcher.svg?maxAge=2592000)](https://www.npmjs.com/package/testingbot-tunnel-launcher)
[![Tests](https://github.com/testingbot/testingbot-tunnel-launcher/actions/workflows/test.yml/badge.svg)](https://github.com/testingbot/testingbot-tunnel-launcher/actions/workflows/test.yml)

A library to download and launch [TestingBot Tunnel](https://testingbot.com/support/tunnel).

## Installation

```sh
npm install testingbot-tunnel-launcher
```

## Usage


### Simple Usage (Callback)

```javascript
const testingbotTunnel = require('testingbot-tunnel-launcher');

testingbotTunnel({
  apiKey: process.env.TB_KEY,
  apiSecret: process.env.TB_SECRET,
  verbose: true
}, function (err, tunnel) {
  if (err) {
    console.error(err.message);
    return;
  }
  console.log("Tunnel ready");

  tunnel.close(function () {
    console.log("Tunnel closed completely");
  })
});
```

### Simple Usage (Async/Await)

```javascript
const testingbotTunnel = require('testingbot-tunnel-launcher');

async function runTests() {
  try {
    const tunnel = await testingbotTunnel.downloadAndRunAsync({
      apiKey: process.env.TB_KEY,
      apiSecret: process.env.TB_SECRET,
      verbose: true
    });
    console.log("Tunnel ready");

    // Run your tests here...

    // Close the tunnel when done
    await testingbotTunnel.killAsync();
    console.log("Tunnel closed completely");
  } catch (err) {
    console.error(err.message);
  }
}

runTests();
```

### Options

```javascript
const testingbotTunnel = require('testingbot-tunnel-launcher')
const options = {
  // The TestingBot API key which you can get for free, listed in the TestingBot member area
  apiKey: 'key',

  // The TestingBot API secret which you can get for free, listed in the TestingBot member area
  apiSecret: 'secret',

  // More verbose output from the tunnel
  verbose: true,

  // Port on which the tunnel Selenium relay will listen for
  // requests. Default 4445. (optional)
  'se-port': 4445,

  // Proxy host and port the tunnel can use to connect to an upstream proxy
  // e.g. "localhost:1234" (optional)
  proxy: null,

  // A comma-separated list of domains that
  // will not go through the tunnel. (optional)
  'fast-fail-regexps': null,

  // Write logging output to this logfile (optional)
  logfile: null,

  // Change the tunnel version - see versions on https://testingbot.com/support/other/tunnel/changelog.html
  tunnelVersion: "4.0",

  // Gives this tunnel a unique identifier
  tunnelIdentifier: "myIdentifier",

  // Share this tunnel with other team members on TestingBot
  shared: true,

  // Timeout in seconds for the tunnel to start (default: 90)
  timeout: 120,

  // Disable SSL bumping/rewriting
  noBump: false,

  // Disable caching
  noCache: false
};

testingbotTunnel(options, function(err, tunnel) {
  console.log("Started Tunnel");
  tunnel.close(function () {
    console.log("Closed tunnel");
  });
});
```

### Credentials

You can pass the [TestingBot credentials](https://testingbot.com/members) as `apiKey` and `apiSecret` in the options.

You can also create a `~/.testingbot` file in your `$HOME` directory, with `apiKey:apiSecret` as contents.


## Testing

```
npm test
```

## MIT license

Copyright (c) TestingBot <info@testingbot.com>