What is TestFairy Connect?
TestFairy Connect is proxy server installed on-premise, designed to help companies connect their bug tracking systems running behind firewall (JIRA Server, TFS), with the TestFairy cloud.
How to Install TestFairy Connect (video tutorial)
How does it work?
The key part of TestFairy Connect is the agent service (TFC Agent) that runs on a system, also behind that firewall, connecting to TestFairy's web app and to your bug tracking system.
This article details the requirements and steps to setting up TestFairy Connect.
For more articles relating to this subject, check out the following links:
- Installing on Windows
- Installing on Linux or Mac
- Configuring Team Foundation Server
- Configuring JIRA with OAuth
- Configuring JIRA with Basic Auth
- nodejs 4.2+
- git 1.7+
For Team Foundation Server (TFS) integration, please refer to that documentation for additional requirements.
Installation is done via npm. Please run the following command in a folder for your TestFairy Connect installation:
npm install git+https://github.com/testfairy/testfairy-connect.git
To configure TestFairy Connect, run the following line and follow the on-screen instructions:
node node_modules/testfairy-connect/service.js configure [-f /path/to/config.json]
You'll need the following data:
- TestFairy API key (found at https://app.testfairy.com/settings/#api-key.
- The URL to your bug system.
- Name of ticket type (JIRA issue or TFS workitem) to be created by TestFairy Connect.
- In the case of a JIRA basic authentication - valid credentials for a bug system user.
- In the case of a JIRA oauth authentication - admin access to JIRA/the ability to manage Application Links (as described in the configuration wizard script).
By default, your configuration file
config.json is located in
.testfairy-connect under the running user's home directory.
- On linux/Mac:
- On Windows:
If the optional
-f parameter is omitted, TestFairy Connect will use the default location.
Running TestFairy Connect
To start the TestFairy Connect agent, use the following command:
node node_modules/testfairy-connect/service.js run [-f /path/to/config.json]
If the optional
-f parameter is omitted, TestFairy Connect will use the default location: /path/to/user/home/.testfairy-connect/config.json
(Optionally) Starting TestFairy Connect as a Windows Service
Upon installation, you'll find
TestFairy Connect in your Windows Services console. Upon successful configuration,
you can try starting the service from the Services console.
Supported issue trackers specific stuff
Team Foundation Server (TFS)
In order to connect to a working TFS server, the machine running the TestFairy Connect agent must have Visual Studio installed. For a free version of Visual Studio, please look at Visual Studio Express
The machine running the TFC Agent must have Microsoft Visual Studio Team Foundation Server 2015 Power Tools installed.
In order to successfully integrate with TFS, the user running the TFC Agent must have write access to the TFS project collection.
It might be a good idea to create a Windows user called e.g. testfairyconnect, with permissions to both run the agent and create issues in TFS.
How to Install TestFairy Connect on Windows Server
The steps below will guide you through installing and configuring your TestFairy Connect environment:
- Step 1: Install the required software
- Step 2: Configure config.json file
- Step 3: Start the TestFairy Connect service
Step 1: Install the required software
TestFairy Connect is written in nodejs. You will also need the TFS Power Tools, which are available for free download.
- (NodeJS) Go to https://nodejs.org/en/download/current/ and download the Windows installation
- If you don't have Visual Studio set up on this computer, you need to install it. TFS Power Tools depends on it to access the TFS server. You can download the Community Edition for free at https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
- Download and install
TFS Power Tools
- Download the the TestFairy Connect zip package from https://github.com/testfairy/testfairy-connect/releases/latest
- Unzip the downloaded package into a new folder. For example, you can name that folder "TestFairy-Connect".
Step 2: Configure
TestFairy Connect's configuration file is a simple json file you can open any text editor (like Notepad) to update the settings.
- Create a folder named
.testfairy-connectin your user's home directory (for example: /Users/GilM/.testfairy-connect)
- Paste the same configuration file from http://docs.testfairy.com/TestFairy_Connect/Configuring_TFS.html into
- Edit the
config.jsonfile and update it to your settings. Please refer to Configuring TFS for more information on this subject.
Step 3: Start the service
After installing and configuring the service, it is time to start the service. You can start TestFairy Connect either manually in a Powershell, or as a Windows Service.
- Open Windows Powertools or Terminal in the folder where you unpacked the zip file, and run:
If all the configuration are correct, you will see a "TestFairy Connect is ready" log. If you have an error, please follow the on-screen instructions.
You now have TestFairy Connect installed and configured, behind your firewall, to work with your Team Foundation Server service.