TestBox Browser SDK


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:

* Communication to TestBox for user experience purposes
* [Client-side Auto-login][1]

$3

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

``javascript
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 web site. 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:

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

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

$3

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:

`javascript
// 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";

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

$3

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:

`javascript
import testbox from "@testboxlab/browser";

testbox.loginHandler = ((email, password) => {
// Use the email and password to log in, either by filling out
// your "login" form and submitting, or some other mechanism.

// After logging in, make sure to redirect the user.
window.location = "/";
});
`

Testing

$3

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

$3

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

[1]: https://partner-docs.testbox.com/docs/autologin/javascript/
[2]: https://partner-docs.testbox.com/docs/iframing/test/