Getting Started

Owned by Michael Harnish
Last updated: Apr 06, 2018
10 min read

Video Tutorial

The fastest way to get started is to watch the following video. It is specifically geared for Windows users, but users on other platform will find the instructions for creating a Toffee Composer account helpful.

This tutorial will walk you through creating an account and writing and executing tests with Toffee Composer release 2.0. If you already have a Toffee account from an earlier release, you will still find useful information on here, especially the instructions for creating and launching Toffee Performer which has been updated for this release.

Before You Start

  1. Before you start, identify your testing workstation - which may be your laptop, or another machine - and install at least one browser on it. Toffee supports Google Chrome, Mozilla Firefox, Microsoft Internet Explorer, and Microsoft Edge. 
  2. If you haven't already, please familiarize yourself with the overview of Toffee. It describes all of the different parts of Toffee and how they work together. This page assumes you are familiar with Toffee Composer and Toffee Performer, and how they work together.

Overview/Quick Start

Following are the steps to start testing with Toffee Composer and Performer. If you already have a Toffee account, skip to step 3.

  1. Create a Toffee Composer account, if you need one. Visit https://app.toffeetesting.io/signup and follow the instructions there. We'll send an activation link to your email, so make sure to enter a valid email address.
  2. Activate your Toffee Composer account, if you haven't already. Check your email (or spam folder) for an activation email from activation@ksmpartners.com. Follow the instructions in the email.
  3. Retrieve your keys. Log in to Toffee Composer with your email address and password, then visit the "My Account" page under the main menu (to the left of the Toffee logo). This page displays your access and secret keys.
  4. Install Toffee Performer on your testing workstation. Download the installer for 64-bit Windows, run it, and follow the prompts. See below for instructions for other platforms.
  5. Start Toffee Performer on your testing workstation. Enter your access and secret keys from the "My Account" page in Toffee Composer (copy/paste recommended), then click the "Connect" button. On successful connection, Performer reports the Performer ID assigned to it.
  6. Start entering commands. Open the Toffee Composer Workspace (main menu > Workspace), select that performer in the "Performer ID" dropdown, and start entering commands. Try start chrome, load page at https://get.toffeetesting.io, and quit all for starters.

These steps are described in more detail below.

Create a Toffee Composer Account

To create a Toffee Composer account:

  1. Open https://app.toffeetesting.io/signup in any browser.
  2. Enter your first and last names. These are required fields.
  3. Enter your email address. This is a required field, and it must be a valid email address. We will send an activation email to this email address, so if it's not valid, you will never receive that email and your account will never be activated.
  4. Create and enter a password, and enter it again on the "Confirm Password" line. These must match, and until they do, the page will display a warning that they don't.
  5. Click the "I'm not a robot" checkbox, if it's displayed. If ReCaptcha prompts for more information to prove you're not a machine - usually by selecting images that meet a certain criteria - do so. We add this step to prevent automated account creation.
  6. Click the "Sign Up" button.
  7. If everything is in order, Composer will prompt you to check your email for an activation email.

Troubleshooting Account Creation

Problem: Composer displays the message "Account with email <the email you entered> already exists" when you click Sign Up.

This means you already have a Toffee account associated with that email address. If you don't remember the password you used to create the account, open https://app.toffeetesting.io/forgot in a browser to request a password reset.

Activate Your Toffee Composer Account

After you've successfully created a Toffee Composer account, we'll send you an email to activate your account. You cannot use your new account until you activate it.

  1. Check your email for a message from activation@ksmpartners.com with the subject "Activate your Toffee account." (If this email is not in your inbox, check your spam folder).
  2. That email contains a hyperlink ("click this link"). Click that link.
  3. Composer displays its login page, with the message "Your account has been activated." Enter your email and the password you chose, and click the "Sign In" button.
  4. On successful login, Toffee Composer displays the Composer Workspace. You are now signed in to Toffee Composer and ready to retrieve your keys.

Troubleshooting Activation

Problem: When I click the activation link, Toffee displays the message "Unknown or already-used activation code."

The most likely cause is that you've already activated your account. If this is the case, enter your username and password and click the "Sign In" button, and the Composer Workspace should display.

If that doesn't work, and if you've copied the URL from the emailed link and pasted it into your browser, make sure that you did not accidentally forget to copy any of the characters from the activation code.

Retrieve Your Keys

To run Toffee Performer, you need to know your access and secret keys. These are used to connect Toffee Performer to Toffee Composer, so that Composer knows which Performers belong to which account. To retrieve your keys:

  1. If you haven't already, log in to your activated Toffee Composer account with your email and password. Toffee displays the Composer Workspace page.
  2. Open the main menu, which is just to the left of the Toffee logo, and choose the "My Account" option.
  3. Your access and secret keys are shown on this page. Your access key is always displayed; to see your secret key, click the "Click to show" link.


 More about your access and secret keys...

Some things you should know about these keys:

  • We use keys, not your email and password, to secure your Performer connections. Your email and password give you full access to your Composer account, and Performer doesn't need full access; it only needs to receive commands that you send it.
  • Your access key is a random 10-character combination of lowercase letters, uppercase letters, and numbers.
  • Your secret key is a random 35-character combination of lowercase letters, uppercase letters, and numbers. 
  • Both your access and secret keys are generated by Composer when you create your account.
  • Your access key uniquely identifies your account to Composer, and it never changes.
  • To prevent others from connecting Performers to your account, you should not share your secret key.
  • If you believe your secret key has been compromised - if, for example, you see Performers connected that you don't recognize - contact us using the "Feedback" button on the right of the Toffee Composer toolbar.

Install Toffee Performer

On 64-bit Windows

These instructions were written for the Google Chrome browser running on Windows 10. If you're running a different browser or a different version of 64-bit Windows, the details of each step may vary slightly.

  1. Download the installer for 64-bit Windows from Toffee's download site (you can also find a link to this file on Composer's My Account page, described above). This file is named toffee-performer-latest.exe, and as its name indicates, it is an executable file. This may take a few seconds or minutes, depending on your internet connection's speed.
  2. When the download completes, click on the downloaded file in the bottom-right corner of your browser. This starts the install process.
  3. The download will display a progress bar as it prepares the installer, and then will pop up a window asking "Do you want to allow this app to make changes to your device?" This window should display KSM Technology Partners LLC as the verified publisher. Click the "Yes" button.
  4. The Toffee Performer Setup Wizard starts; click the "Next >" button.
  5. The Setup Wizard displays the Toffee Performer license agreement. Read the agreement, and if you accept its terms, click "I accept the agreement" and click "Next >"
  6. The Setup Wizard asks you to select a destination directory; this is where the Toffee Performer files will be installed. Accept the default, which for most people will be C:\Program Files\ToffeePerformer. You can override this by clicking the "Browse..." button, but if you do so, make sure you have privileges to install in the directory you choose. Click "Next > ".
  7. The Setup Wizard installs Toffee Performer in the directory you chose. When the install is complete, it displays the message "Completing the Toffee Setup Wizard" and lets you know that it has finished installing Toffee Performer. Click "Finish".
  8. Verify your installation by clicking the start menu; on Windows 10, this is the Windows icon in the bottom left of your screen. You should see a new "Toffee Performer" program group. Note that the installer does not install an icon on the desktop.

On MacOS

ToffeePerformer is available for the MacOS as a .tar.gz archive. It bundles a Java Runtime Environment, as well as current drivers for the latest versions of Chrome and Firefox. It supports Safari, too, using the Safari WebDriver built-in to the MacOS.

To install ToffeePerformer on MacOS:

  1. Visit the Downloads page and download the current version for MacOS.
  2. Move the file to the directory where you want to install Toffee Performer (e.g., your Documents directory).
  3. Double-click the .tar.gz file, which will create the ToffeePerformer directory next to the .tar.gz file (which you can now move to the trash).
  4. Open a terminal, change to the ToffeePerformer directory, and run ./performer.sh. This will start Toffee Performer.
  5. Enter your access key and secret key where prompted, and click the Connect button. The next time you run Toffee Performer, it will remember your keys.

To uninstall ToffeePerformer, simply remove the ToffeePerformer directory.

On other platforms

(Toffee also supports 64-bit Linux installations. We will post these instructions for these soon. If you need these before we do, please contact us via the Toffee Composer "Feedback" button and we'll help you through the process.)

Start Toffee Performer

Before you start Performer for the first time, you will need to have created a Composer account, activated it, and retrieved your access and secret keys. You will also need to have installed Toffee Performer. These steps are all described above.

On 64-bit Windows

To start Toffee Performer on 64-bit Windows:

  1. Launch Toffee Performer from the Windows start menu.
  2. Toffee Performer displays its login screen, which will prompt you for your access and secret keys. Copy and paste them from the Composer "My Account" screen, as described above.
  3. Click the Connect button.
  4. If you entered your access and secret keys correctly, Toffee Performer will display a new screen, with the word "Connected" or "Reserved" at the top:
    1. If you have already logged into Composer without connecting to a Performer, Composer will automatically reserve the Performer you just started up. Performer displays the status "Reserved."
    2. If you haven't logged into Composer, or if you have but have reserved a different remote, Performer displays the status "Connected."
  5. Every time you connect Performer to Composer, Composer assigns a unique, random Performer ID. Make note of your Performer ID, which is displayed at the top of the Performer screen when the performer is Connected or Reserved.
Once you've successfully connected Performer to Composer, Performer saves your access and secret keys in a file called .toffee_keys in your home folder (e.g., C:\Users\<Windows username>). The next time you connect Toffee Performer, it will read your keys from this file, so you don't have to enter them every time.

On MacOS

  • Open a terminal
  • Change to the ToffeePerformer directory you created during install (e.g., cd ~\Documents\ToffeePerformer)
  • Type ./performer.sh. This will start Toffee Performer.
  • Enter your access key and secret key where prompted. Copy and paste them from the Composer "My Account" screen, as described above.
  • Click the Connect button.
  • If you entered your access and secret keys correctly, Toffee Performer will display a new screen, with the word "Connected" or "Reserved" at the top:
    1. If you have already logged into Composer without connecting to a Performer, Composer will automatically reserve the Performer you just started up. Performer displays the status "Reserved."
    2. If you haven't logged into Composer, or if you have but have reserved a different remote, Performer displays the status "Connected."
  • Every time you connect Performer to Composer, Composer assigns a unique, random Performer ID. Make note of your Performer ID, which is displayed at the top of the Performer screen when the performer is Connected or Reserved.
Once you've successfully connected Performer to Composer, Performer saves your access and secret keys in a file called .toffee_keys in your home folder (e.g., /Users/<username>). The next time you connect Toffee Performer, it will read your keys from this file, so you don't have to enter them every time.

On other platforms

(Toffee also supports 64-bit Linux testing workstations. We will post these instructions for it soon. If you need these before we do, please contact us via the Toffee Composer "Feedback" button and we'll help you through the process.)

Enter Commands in the Composer Workspace

So far, you've created and activated your Toffee Composer account, retrieved your keys, and used them to run Toffee Performer on your test workstation. If you've made it this far, you're ready to start testing with Chrome, Firefox, or Internet Explorer.

Figure 1: Session ID BCDU5TKQRtjdnx2 connected to Performer ID HWo35xBgjUBsgz1

  1. If you haven't already, open a web browser and log in to Toffee Composer with the email and password you created above.
  2. Toffee Composer assigns you a Session ID, displayed at the left of the Composer toolbar. See Figure 1, above.
  3. If there is a connected, unreserved Performer from your account, Toffee Composer reserves it for you and displays its performer ID in the Composer toolbar, just to the right of the session ID button. See Figure 1, above.
    1. If the Performer ID button says "Not connected," click it and select your Performer ID from the dropdown.
  4. Look at Performer and verify that it's status is Reserved, and that the reserving session ID matches the one in Toffee Composer.
  5. Back in Composer, select "Workspace" from Toffee's main menu (to the left of the Toffee logo).
  6. In the text box at the bottom of the Workspace screen, type the command start chrome (or start firefox or start internet explorer). If everything is configured correctly, a test browser will start. (What about Microsoft Edge? Click here for instructions for testing with Edge.)
  7. Type the command load page at https://get.toffeetesting.io into the Workspace. The test browser displays the Toffee web site.
  8. Type the command quit all. The test browser closes.
  9. (You can log out of Toffee Composer at any time, or close Toffee Performer.)

That's it: you're off and running with Toffee. Visit the User's Guide to learn additional commands, or how to build and run test scripts.

Using Toffee with Microsoft Edge

Toffee Composer supports Microsoft Edge as a browser. Because of Microsoft licensing restrictions, however, we cannot distribute the software Toffee Performer needs to control Microsoft Edge. You must install this yourself. Fortunately, this is a simple process:

  1. From your testing workstation, open a browser, visit https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ and follow the instructions there to download MicrosoftWebDriver.exe appropriate for your system.
  2. Move MicrosoftWebDriver.exe it to the webdrivers\win64 folder of your Toffee Performer installation directory. This is the installation directory you chose when you installed Toffee Performer; the default, on 64-bit Windows, is C:\Program Files\ToffeePerformer\webdrivers\win64.
  3. From Toffee Composer's Workspace, enter the command start edge to start the Edge browser.

Unfortunately, Microsoft Edge does not allow you to open two instances of Microsoft Edge on the same computer. This means that you cannot open Toffee Composer in Microsoft Edge, connect to an instance of Performer running on the same computer, and enter the command start edge.

Microsoft has not announced any plans to allow Microsoft Edge to run multiple instances on the same machine.

There are two workarounds to this problem:

  1. Use Composer in Chrome or Firefox any time you need to test Microsoft Edge with the start edge command.
  2. If you don't have access to Chrome or Firefox, use Composer in Microsoft Edge on one computer, and install and run Performer on a different computer (after installing MicrosoftWebDriver.exe as described above).



On this page