Skip to main content

TestBox JavaScript

Because your web app and TestBox operate on different domains, it is impossible for our front-end to make inquiries about the status of the iFrame directly. As such, we have built messaging infrastructure to communicate the health and status of the iFrame. This requires a small amount of JavaScript to be added to your HTML head, as shown here:

Installation​

First, install the package in to your front-end.

npm i @testboxlab/browser

yarn add @testboxlab/browser

Usage and Purpose​

This package provides two sets of functionality:

Base Usage​

If you just need the basics of TestBox for your app, you'll use something like this:

import {startTestBox} from "@testboxlab/browser";

startTestBox({
    allowFullStory: true,
    // Allowing FullStory allows us to give you insights into how users
    // are using your web application compared to others. However, it is
    // explicitly opt-in in case you do not wish for your environments
    // to be recorded.
});

This will allow TestBox to communicate with your website. This communication is important to remove loading states and generally provide a good user experience.

If you use React, your implementation might look like this:

import {startTestBox} from "@testboxlab/browser";
import {useEffect} from "react";

export default function App() {
    useEffect(() => {
        startTestBox();
    }, []);
}

If you use react-router, or any kind of client-side routing, you may want to override our standard navigation behavior. Navigation happens when a user chooses a use case they want to try out. By default, TestBox will use window.location to push the iFrame to a new URL. You might want to do something more sophisticated.

There are two ways to interact with the browser SDK for events:

// Option 1: you can use the config object
startTestBox({
    navigateHandler: (url) => {
        history.push(url);
    }
});

// Option 2: you can set the handler directly
import testbox from "@testboxlab/browser-sdk";

testbox.navigateHandler = (url) => {
    history.push(url);
};

Auto-login​

If you have opted to use our client-side auto-login functionality, you have a bit more work to do.

On your login page/component, you will want to add some code similar to the following:

import testbox from "@testboxlab/browser";

testbox.loginHandler = async ({email, password, totp_token, first_name, last_name}) => {
    // The fields above are currently the items you have access to using in your login function
    // 
    // So where do these come from? During trial creation, your integration will return a 
    // set of account credentials in the form of a TrialUser object. We save these creds
    // and then pass them to the app when one of our user starts testing the product
    
    // The return value for this function should be the relative path the user should be redirected to
    // after login

    // For example

    await authService.login(email, password);
    // After logging in, return the next url, testbox will redirect
    return "/dashboard";

    // or 

    const resp = await fetch("/pedals/login/", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        }
    });
    if (resp.status === 500) {
        throw Error("Error: retrying login");
    } else if (resp.ok) {
         // After logging in, return the next url, testbox will redirect
        console.log("Logging into Pedals!");
        return "/dashboard";
    } else {
        console.log("Failed to log into Pedals!");
        return false;
    }
}

Like navigation, you can also configure this at run time:

startTestBox({
    loginHandler: doLoginFunc
});

Testing​

Work in progress! For now, we will test this for you. But soon you will have a place to manage and validate this info.

Testing your installation​

If you'd like to verify that you have installed the script correctly, you can use our self-check tool which can verify that everything is working!

Package testing​

If you want to test this package, simply run npm run test. It will run the Cypress tests locally.