Quickstart

You can create and deploy end-to-end tests in just a few minutes by running a couple of terminal commands, then teaching TestDriver what to do on your local machine.

Introduction

Making tests with TestDriver is super easy! Just show TestDriver what to test on your local machine and upload the resulting test plan. Then TestDriver will repeat the test on it's own machine on every commit!

For this example, we'll be testing an example todo app. The live site is here, and the source for this quickstart is here.

TestDriver is not limited to web apps! It has full control of the desktop so you can test desktop apps, browser extensions, or anything else!

Prerequisites

You'll need NodeJS version 20 to get started. Windows users will need a couple extra tools.

Install tools with Chocolatey

Install Python & Visual Studio Build Tools

choco install python visualstudio2022-workload-vctools -y

Install NodeJS

You will also need NodeJS if you don't have it yet.

choco install nodejs-lts --version="20.17.0"

Set Execution Policy

Open a new terminal with admin privileges and execute the following command : 

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

This gives TestDriver the right to execute it's scripts and is only valid for the current user.

Setup

Install TestDriver via NPM

Install testdriverai via NPM. This will make testdriverai available as a global command.

npm install testdriverai -g

Set up the project

Make a new folder. In the root of the folder, run testdriverai init. This will configure your TestDriver experience and set up a basic GitHub runner workflow.

testdriverai init

If you are working with a single display, we recommend enabling desktop notifications and speech narration.

You're almost ready to deploy your first test!

Set up your test environment

Before we get started, let's set up your machine to collaborate with TestDriver.

Display

TestDriver isn't like any framework you've used before. TestDriver makes decisions based on what it can see on your display!

TestDriver only knows about what it can see on your primary display!

For now, set up your environment with a browser window and your terminal side by side like so:

When you enter commands into TestDriver, the focus-window command will bring Chrome or other applications to the foreground.

Enabling TD_SPEAK and TD_NOTIFY will help you understand what TestDriver is doing when the terminal is not visible.

Application State

The application you want to test should be visible before you run the testdriverai command.

When TestDriver runs tests on it's own machine, we'll use a prerun.sh script to build and launch the app. For now though, it's easier to do it yourself.

For our example, make a new incognito window in Chrome and load our test webpage:

https://testdriverai.github.io/example-react-todo/

Teach TestDriver

It's time to test! The following command will launch TestDriver in interactive mode. TestDriver will generate test commands and save them totestdriver/test.yml.

testdriverai testdriver/test.yml

Instruct TestDriver

Now, just tell TestDriver what you want it to do. For our example, try click new task.

> click new task

Later, we'll use /explore to perform higher level objectives like "make a new task"

TestDriver Generates a Test

TestDriver will look at your screen and generate a test script. TestDriver can see the screen, control the mouse, keyboard, and more! 

> click new task

    thinking...

    To accomplish the goal of clicking "New Task" on the
    webpage, we need to focus on the browser window and then
    click the "New Task" button.

    Here is the YAML code to achieve this:

    commands:
      - command: focus-application
        name: Google Chrome
      - command: hover-text
        text: New Task
        description: button to create a new task
        action: click

command='focus-application' name='Google Chrome'
command='hover-text' text='New Task' description='button to create a new task' action='click'

    thinking...

    Based on the provided coordinates and text, the element
    that matches "New Task" with the description "button to
    create a new task" is at coordinates (864, 328).

    Here is the YAML code to click on that element:

    commands:
      - command: click
        x: 864
        y: 328
        click: single
        button: left

command='click' x=864 y=328 click='single' button='left'

TestDriver executes the test script

TestDriver will execute the commands found in the yml codeblocks of the response.

See the yml TestDriver generated? That's our own schema. You can learn more about it in the YML Schema.

Take your hands off the mouse and keyboard while TestDriver executes! TestDriver is not a fan of backseat drivers.

Keep going!

Feel free to ask TestDriver to perform some more tasks. Every time you prompt TestDriver it will look at your screen and generate more test step to complete your goal.

> enter a task title
> enter a task summary
> click create task
> delete the task

Save the test

  • If everything worked perfectly, use the /save command to save the test script to the current file.

  • If something didn't work, you can use /undo to remove all of the test steps added since the last prompt.

Test the test locally

Now it's time to make sure the test plan works before we deploy it. Use testdriver run to run the test file you just created with /save . 

testdriverai run testdriver/test.yml

Make sure to reset the test state!

Deploy

Now it's time to deploy your test using our GitHub action! testdriver init already did the work for you and will start triggering tests once you commit the new files to your repository.

git add .
git commit -am "Add TestDriver tests"
gh pr create --web

Your test will run on every commit and the results will be posted as a Dashcam.io video within your GitHub summary!

You must add your TESTDRIVER_API_KEY as a GitHub secret in your repository

PreviousIntroductionNextPricing

Last updated