Quick Start with testflowkit

Prerequisites

• Chromium installed: testflowkit uses Chromium for web testing.
  • testflowkit install automatically chromium but you can install yourself chormium
  • Click here for instructions on how to install Chromium.
• Understanding of Gherkin: Gherkin is the language used to write your test scenarios. Refer to this guide to learn more about Gherkin.
• Understanding of YAML: testflowkit uses YAML for configuration. This tutorial provides a quick introduction to YAML.
• Command Line Interface (CLI): You'll need to be comfortable using a CLI to run testflowkit commands.

Objective

In this exercise, we will test our own documentation. We will make sure that the search for phrases works correctly.

Installation and configuration

1. Download testflowkit for your operating system: Download link. Place the executable in the folder of your choice.
2. Extract tkit for the downloaded zip in the folder of your choice. its contains a binary named tkit
3. Open your terminal and type the following command:

   
   tkit init --appname=test_app
       

   
   This command creates the configuration files `frontend.yml` and `cli.yml` at the root of the folder.
   The `frontend.yml` file contains the settings specific to your web application, while the `cli.yml` file contains the general settings for testflowkit. and a folder containing an gherkin example

Writing the test

Let's start by writing our tests in natural language. You can go to the reference page to perform the actions and note them. Once finished you can unroll our suggestion.

Interactive Tutorial: Writing a Gherkin Scenario

Let's walk through creating a Gherkin scenario step-by-step. Our goal is to write a test that verifies the search functionality on the sentence referencing page.

Here are the actions we want to test:

1. Open the browser.
2. Go to the sentence referencing page.
3. Type "browser" into the search field.
4. Verify that the following sentence appears on the screen:

   
   I open a new browser tab
       

Now, let's translate these actions into Gherkin code.

Step 1: Create a Feature File

First, create a new file named search.feature in your features directory. This file will contain our Gherkin scenarios.

Step 2: Define the Feature

Start by defining the feature we are testing. In this case, it's the search functionality. Add the following line to your search.feature file:

Feature: Search Functionality
    

Step 3: Write the Scenario

Next, define a scenario within our feature. A scenario outlines a specific test case. We'll do this in stages:

Stage 1: Setting the Scene

Add the following line to your file:

Scenario: Search for a sentence
    

This gives our scenario a descriptive name.

Stage 2: Starting Point

Now, let's define the starting point of our test. Add this line:

Given I open a new browser tab
And I navigate to sentences referencing page
    

This "Given" step sets the initial context for the scenario. It says we begin on the sentence referencing page.

Stage 3: User Action

Next, describe the action the user performs. Add this line:

When I type "browser" into the search field
    

This "When" step specifies the user action – typing "browser" into the search field.

Stage 4: Expected Outcome

Finally, define the expected result of the user's action. Add this line:

Then I should see on page "I open a new browser tab."
    

This "Then" step states the expected outcome – seeing a specific sentence on the page.

Save the search.feature file.

Defining Variables

You can define variables in the frontend.yml file to make your scenarios work smoothly. These variables represent elements on your web page and make your Gherkin code more readable and maintainable.

Here's how it works:

• Page URLs: Store the URLs of frequently used pages, like the sentence referencing page. This way, you can refer to them by name in your scenarios. For example:

  
  sentences_reference: "http://<doc-base-url>/sentences"
      

• UI Elements: Define variables for interactive elements like buttons, input fields, etc. This makes your Gherkin steps clearer and easier to understand. For example, instead of writing a complex CSS selector in your Gherkin step, you can use a variable like search_field.

Important Tip: You can even specify multiple CSS selectors for a single element! This is helpful if the element might be identified differently in various parts of your application. Etools will try each selector in order until it finds a match.

Naming Convention: To keep your code organized, use underscores to separate words in variable names (e.g., login_button instead of loginButton). This is a common practice in YAML files.

Here's an example of how your frontend.yml file might look:

# frontend.yml
global:
  elements:
    search_field:
      - input[type='search'] 
      - .search-input 
    category_button: 
      - .menu-link 
        
   pages:
    sentences_referencing: "/sentences" 
   
   base_url: "doc-base-url"
    

Remember: Replace <doc-base-url> with the actual base URL of your documentation.

Running the tests

Run the following command in your terminal to launch the e2e tests:

./tkit run
    

This command will execute your Gherkin scenario and provide you with a report of the test results.

Congratulations! You've successfully written a Gherkin scenario to test the search functionality. You can now expand on this by adding more scenarios to cover other test cases.

Troubleshooting

If you encounter errors while running your tests, here are a few things to check:

• Make sure your antivirus is not blocking the installation of Chromium.
• Verify that you have correctly defined the variables in your frontend.yml file, especially the base URL of your documentation and the CSS selectors for the UI elements.
• Consult the testflowkit documentation for more detailed information on troubleshooting and resolving errors.

Useful Resources

• testflowkit Configuration
• testflowkit Sentence Repository

Next Steps

Now that you've learned the basics of testflowkit, here are some suggestions to go further:

• Write more complex Gherkin scenarios to test different parts of your web application.
• Explore the possibilities of integrating testflowkit with other testing and automation tools.
• Contribute to the testflowkit project by reporting bugs, suggesting improvements, or developing new features.