Getting started

Edited on March 14, 2017

Basic installation

First, download and unzip a step archive from the github release of your choice (and follow the instructions in the installation page of the corresponding version of the documentation). There are two primary STEP components that you need to download and install initially :

step-controller-X.Y.Z.zip
step-agent-X.Y.Z.zip

These files are available for download here :  https://github.com/denkbar/step/releases/latest

You also need a running instance of mongoDB.

For additional platform-specific libraries, you will need to download our windows-binaries.zip or linux-binaries.tar.gz archives. That's required for drivers such as firefox or phantomjs.

  • MongoDB

    • Download at : https://docs.mongodb.com/master/administration/install-community/

    • Install a mongodb instance locally or on the host of your choice. If the mongodb Instance is not running locally, you will have to update the controller's configuration file (step.properties) to point at the remote mongodb instance.

    • If you wish to customize the hostname, port number and other options such as credentials, you will have to edit your "step.properties" file in the conf/ folder of the controller. During your first attempt at installing step, we would recommand using the standard setup and installing everything on one machine. Every piece of the architecture can be moved very easily later on.

    • We placed a convenience script inside of the bin/ folder of the controller to start your mongoDB instance and store its data locally (inside of the data/ folder). However, if you started a mongoDB instance on your own, that's fine too.

  • Controller

    • If java is not already on your PATH, then set your java path if necessary (JRE 1.8+ is preferred)

      • Windows environment: watch out if you set the path, the last backslash character needs to be positionned after the quotes ! For instance:
        SET JAVA_PATH="D:\Program Files\Java\jdk1.8.0_73\jre\bin"\
    • Start the script corresponding to your OS in the bin folder of the step-controller archive:

      • startController.bat for Windows

      • startController.sh for Linux (you might need to chmod +x the file first)

      • startController.command for Mac OS (you might need to chmod +x the file first and then right click -> Open, and agree to the GateKeeper confirmation message)

    • ​The web application should now be accessible under http://localhost:8080/

  • Agent

    • If java is not already on your PATH, then set your java path if necessary (JRE 1.8+ is preferred)

      • Windows environment: watch out if you set the path, the last backslash character needs to be positionned after the quotes ! For instance:
        SET JAVA_PATH="D:\Program Files\Java\jdk1.8.0_73\jre\bin"\
    • Start the script corresponding to your OS in the bin folder of the step-controller archive:

      • startAgent.bat for Windows

      • startAgent.sh for Linux (you might need to chmod +x the file first)

      • startAgent.command for Mac OS (you might need to chmod +x the file first and then right click -> Open, and agree to the GateKeeper confirmation message)

  • Test your setup

    • You should be able to connect to step using (by default) the address http://localhost:8080 with the following user and login information :

      admin // init
      • Note: If you're migrating from v3.0 or v3.1 to v3.2, this won't work if you haven't first dropped the controllerlogs collection :

        • connecting to: test
          MongoDB> use step
          switched to db step
          MongoDB> db.controllerlogs.drop()
          true
        • Check the page Quick Migration for more details on how to migrate, if needed.

      • If it still isn't the case, see our troubleshooting page for more details or contact us.

    • You should find a couple of demo Keywords under the tab "Keywords"

    • You should find a couple of demo Test Plans under the tab "Plans"

    • You should see a connected agent with a capacity of 10 under the tab "Grid"

    • Clicking the ► button on a Test plan should trigger that Test Plan's execution, which should complete successfully (step status = PASSED, in green).

      • Check our troubleshooting section or open an issue on the github project if you run into some sort of error which you don't understand.​

    • If you run into errors, please feel free to use the the form at http://denkbar.io/contact/ to email us your question or error message, or alternatively post it as an issue in the github project or on Stack Overflow and send us the link.

  • Install platform-specific binaries

    This step is only necessary if you intend to use the firefox or phantomjs drivers for Selenium 3.0. All of the other features of step are available instantly upon download and execution.
    • All you have to do is copy the content of the different binary folders into the agent's ext/bin/ sub-folder.

    • If you wish to plug your own existing binaries, just edit the parameters inside of the "Parameters.js" file, located in the conf/ folder of the controller.

    • Use the windows-binaries.zip file for windows and the linux-binaries.tar.gz file for linux (see the two buttons below). Due to a temporary problem in our filer, the linux archive needs to renamed to .tar.gz after download.

      • windows-binaries.zip  
         
      • linux-binaries.tar.gz
         
      • If you wish to change the preconfigured path, look at the variables set inside of the file Parameters.js in the conf/ folder of the controller.
      • ​​​

Prepackaged examples

In the following sections you will find a number of prepackaged Demo objects made available to you out-of-the-box. These examples are packages of 3 objects : a script (written in various languages), one or more Keyword objects (which you can find under the tab "Keywords" in step and a TestPlan object (which you can find under the tab "Plans"). The idea here is for you to study these objects and execute the TestPlan object to see how scripts are invoked and how the information flows through these different objects.

In the section "Out-of-the-box libraries", we will present the packages which work immediatly upon installation, without having to install any third party library or platform-specific component.

In the section "Platform-specific libraries", you will find additional examples which require for you to copy binaries into the extension folder of the agent, as explained in the "Basic Installation" section above. This is due to the fact that certain components are platform-compiled binaries which we don't want to ship as part of our build. Instead we make them available to you and you can then decide to download and use them or to use your own versions.

Out-of-the-box libraries

step ships with a number of libraries :

- multiple JSR-223 compliant interpreted languages (such as Nashorn Javascript, Groovy and Jython)

- and pure java libraries (such as Selenium's HTMLUnit driver or our modified version of Grinder)

These librairies can be instantly used and we've prepackaged sample Keywords, Scripts and TestPlans for you to execute as soon as you install step, and which you can study in order to create your own scenarios.

We believe shipping examples is the best way for people to learn how to use step, interact with the tool and understand its logic. However, you will also find all of the details and internals necessary to customize the way you install and use step in the documentation.

Executing a test plan will take you to the execution view, where you will see if the corresponding steps succeed or fail, and why.

All of the default scripts will be located inside the data/script folder of the agent. You can edit these scripts, play with them and see how they relate to the Keyword and TestPlan objects, which you can also edit, to figure out how to create your own.

Platform-specific libraries

Some libraries require the use of platform-compiled binaries such as the firefox and phantomjs drivers for Selenium. The generic Keyword "ExecuteProcess" is, in itself, platform agnostic, but the execution of the keyword will rely on processes that are specific to the underlying platform. Therefore, the Demo_Testcase_ProcessExecution has a Windows and a Linux version (we may add additional examples for Mac OS later on, but the process is identical).

In order to install platform-specific binaries easily, we've prepackaged a folder (ext/) into which you can copy these binaries and they will be found automatically by step. In addition, we've built a zip file for windows and linux which contain supported versions of most of the binaries you may want to use in your testing projects. Please refer to the section Basic Installation (see paragraph "Install platform-specific libraries" for instructions on how to install these binaries).

This applies to :

- the gecko driver binary file for Selenium

- the Firefox, Chrome (and obviously Internet Explorer) binaries for Selenium

- the PhantomJs binary file for Selenium

Custom linking and installation

As stated above, we've prepackaged relative folders and variables in order to make these libraries as click'n'play as possible. However, you may want to override some of these default variables in order to organize the different folders and links in a custom way.

All of the details you need to achieve will be given later in a dedicated documentation page, but what you will find in the next sections should already help you create your own Keywords and Test Plans and execute them.

Also if you need to move the platform-specific binaries, take a look at the preconfigured paths of the Parameters.js file in the conf/ folder of the controller.