Getting Started

Everyone has to start somewhere and if you’re new to VIVIDUS, this is where to begin.

Before you start

In order to use VIVIDUS effectively, you need to know what it is and understand some of its fundamental concepts. So before you start using VIVIDUS in earnest, we highly recommend you read "How to cook VIVIDUS?".


Install and configure Git

  1. Download and install Git client

  2. Configure your identity

Install Java

  1. Download and install Java 17.

  2. Configure JAVA_HOME environment variable to point your directory with installed JDK.

  3. Add new entry to PATH environment variable:

    • for Windows: %JAVA_HOME%/bin

    • for macOS / Linux: $JAVA_HOME/bin

Setup test project

  1. Login to GitHub (create a new account at first if you don’t have any).

  2. Create test project repository:

    get an existing test project from GitHub …​
    • Navigate to the target VIVIDUS tests repository page (e.g. vividus-sample-tests)

    • Create a fork of the target tests repository to be able to execute and modify scripts at your convenience:

      • click Fork icon at the top-right corner of the screen,

      • the pre-populated values cover the average user needs, so just click Create fork button,

      • as the result you now have a copy of the target tests repository at your personal GitHub account.

    or generate your own empty project based on the starter project.
    • Open generator.

    • Provide repository name for your test project.

    • Choose option to set visibility of your repository: Public or Private (Private is recommended from start, it can be changed in future).

    • Click Create repository from template button.

  3. Clone your newly generated repository:

    git clone --recursive your_generated_project_url.git
  4. Go to the local directory with your cloned repository:

    cd your_repository_name
  5. Build the project:

    • macOS / Linux:

      ./gradlew build
    • Windows:

      gradlew build

Use IDE for the tests development

Please choose any of the listed below IDEs.



Import the project

  1. Generate Eclipse configuration files:

    • macOS / Linux:

      ./gradlew eclipse
    • Windows:

      gradlew eclipse
  2. Import the project to Eclipse

  3. Start creating your tests

Visual Studio Code


Open the project in Visual Studio Code

  1. Open Visual Studio Code.

  2. Click File  Open…​.

  3. Open a folder with a VIVIDUS project.

  4. Wait until the message Project with the name '…​' is loaded appears.

  5. Start creating your tests.

Execute tests

  1. Open Command Palette by clicking View  Command Palette…​.

  2. Type VIVIDUS: Run Stories in the search bar and select matched command.

  3. Find the tests execution progress logged in the Output console (if it’s closed open it by clicking View  Output).

Execute the tests via CLI

  1. Execute your tests via Gradle:

    • macOS / Linux:

      ./gradlew runStories
    • Windows:

      gradlew runStories

View the test execution report

At the end of any test run, VIVIDUS will give you a link to where the corresponding test report was published. It should look like this:

2022-05-23 13:38:15,523 [main] INFO - Allure report is successfully generated at /dir/to/where/the/results-are-published/.out/vividus-demo/reports/allure/index.html

Modern browsers don’t allow to open the report hosted on the local filesystem due to security restrictions. The following options could be considered.

Option 1 (Safe, but a bit complicated)

  1. Go into the directory:

    cd /dir/to/where/the/results-are-published/.out/vividus-demo/reports/allure
  2. Start a webserver of your choice, in the example below we are using a node webserver through port 3456:

        ✔ ~/dir/to/where/the/results-are-published/.out/vividus-demo/reports/allure
        $ http-server -p 3456
  3. Launch a browser, type localhost:3456 into the URL. If you followed the instructions properly, you should see your report.

Option 2 (Relax browser security)

  1. Tune CORS option in the browser of your choice.

    Make sure this browser will be used to view test reports only, it’s not safe to surf the Internet with relaxed security rules.
  2. Go to the test report directory and open index.html in the configured browser.

Option 3 (VSCode Live Server)

  1. Open Visual Studio Code

  2. Install Live Server extension (to get help on how to install extensions in VSCode please see Install an extension guide)

  3. Click File → Open Folder…​ in VSCode menu and choose the following folder:

  4. Open index.html file

  5. Click Go Live icon residing on right side of the bottom bar and wait until report is opened

The Live Server extension supports hot reload so you can run the tests and then just refresh report page in the browser to see actual results, however the VSCode session should remain active.