Creating your First Coded Test using TDK

🚧

TDK Feature

This is not supported in Testim's visual editor.

Getting started with Testim is easy and simple. We will grab and install a bunch of things for you and you will generally not have to take care of things like "Installing a Grid" that are commonplace in Selenium-based architectures.

🚧

Note: you should already have the Testim Extension installed in order to use the CLI tool effectively in the Dev Kit.

Installing Testim

Testim requires that you have Node.js and NPM installed (we support recent versions of Node). If you do not already have those two tools installed please install them first. Installing with yarn or pnpm is also supported.

Install testim with NPM:

npm install -g @testim/testim-cli

Initialize a new project:

testim init 'my-awesome-project'

This will create a new Testim Dev Kit project. You can read more about the project structure here.

Change into your newly created project directory and make sure the project is linked to your Testim account by running the following:

# Change into the project directory
cd my-awesome-project

# Link the project to your Testim account
testim --login

📘

The --login command will open up a web browser in which you will be asked to login to your Testim account. Once done, the TDK project will be linked to your account and the credentials stored in ~/.testim. For future reference your credentials can be found under the ⚙️settings page in your Testim account.

You can now run your tests from the terminal by running

npm start

For debugging, run your tests directly in VSCode or WebStorm using the pre-built configurations that were created during the project initialization:

You can view the execution results in your Testim account. You can read more about viewing and understanding test results here.

What was created by testim init

You will see the following structure created by testim init:

node_modules/     # installed dependencies
tests/            # this folder contains all your tests
 - test.js        # an example test you can run
package.json      # all your Node.js dependencies, you can edit this and include any Node dependency in your test
package-lock.json # used by NPM to ensure packages always install the same way
.gitignore # So you don't accidentally commit node_modules to your source control

You can run those tests with:

npm run dev-test

Alternatively, you can run this manually with:

testim run ./tests/*.js -m selenium --host localhost --port 4444 --require-credentials

The interesting file here is test.js. Let's take a look at what a Testim Code test looks like:

Anatomy of a test

The following sections exist in a test. Typically tests use Mocha or Jest syntax. Using modern async/await JavaScript and tests are written using describe/it or test syntax.

Testim will automatically generate live results and screenshots on the fly when you execute code actions.

Here is an annotated example of what a test looks like:

"use strict";

// Import Testim Dev Kit methods
const { go, text, test, l, Locator } = require('testim');

// Import chai assertion library
const { expect } = require('chai');

// Load the smart locators data and make it available for use in this test
Locator.set(require('./locators/locators.js'));

test('Simple text validation', async () => {
  await go("http://demo.testim.io");

  // Grab the title text and store it in a const
  const title = await text(l("SPACE_&_BEYOND"));

  // Use Chai to assert the title text is correct
  expect(title).to.eq('Space & Beyond');  
  
}); // end of test

Running the tests locally and in your CI

The easiest way to run all the tests locally is to run:

npm test

And for your CI server, clone your Testim Code project and simply run:

npm run ci

Note: Please see running Testim on your CI for more general CI related instructions. There are also specific instructions for popular CI servers such as Circle CI, Jenkins, TeamCity and others.

When tests run locally they run on a single browser (Chrome) by default but it is possible to pass the testim command a --browser argument containing what browser to run (for example --browser firefox) or to run them on a Grid. To use a grid please see the Grid documentation. We support running on your own grid, on our managed grids or on any grid provider such as Browserstack or Sauce Labs.

What now?

Great, now that you have Testim installed continue to the tutorial.