Quick Start

In this tutorial, you'll learn how to set up a test project and write your first automated test with TestFlowKit.

Prerequisites

Before starting, make sure you have TestFlowKit installed:

npm install -g @testflowkit/cli
tkit --version

npx @testflowkit/cli --version

# Download from GitHub Releases
# https://github.com/TestFlowKit/testflowkit/releases
./tkit --version

What We'll Build

We'll create a simple test that:

Visits a web page
Interacts with a search field
Verifies the search results

Step 1: Create Project Structure

Create a new folder for your test project with the following structure:

my-test-project/
├── config.yml
└── features/
    └── search.feature

Step 2: Create Configuration File

Create a config.yml file in your project folder:

settings:
  page_load_timeout: 30000
  think_time: 100
  concurrency: 1
  report_format: "html"
  gherkin_location: "features"

env:
  base_url: "http://localhost:3000"

frontend:
  base_url: "{{ env.base_url }}"
  default_timeout: 1000
  headless: false
  screenshot_on_failure: true
  
  pages:
    sentences: "sentences"

  elements:
    common:
      search_field:
        - "#search-input"

Configuration Breakdown

Section	Purpose
`env`	Environment variables like frontend and API URLs
`settings.page_load_timeout`	Maximum wait time for page loads (ms)
`settings.think_time`	Delay between actions (ms) for debugging
`settings.report_format`	Output format for test reports
`settings.gherkin_location`	Folder containing feature files
`frontend.default_timeout`	Default timeout for element interactions (ms)
`frontend.headless`	Run without visible browser window
`frontend.screenshot_on_failure`	Capture screenshots when tests fail
`frontend.pages`	Named page paths
`frontend.elements`	Element selectors grouped by page with fallbacks

Step 3: Write Your First Test

Create a search.feature file in the features folder:

Feature: Search Functionality

  Scenario: User can search for sentence
    Given the user goes to the "sentences" page
    When the user enters "field" into the search field
    Then the user should see "the user enters {string} into the {string} field" on the page

Understanding the Syntax

Feature: Describes the feature being tested
Scenario: A specific test case
Given: Sets up the initial state
When: Describes the action
And: Adds additional actions or assertions
Then: Describes the expected outcome

Step 4: Run Your Test

Open a terminal in your project folder and run:

tkit run

TestFlowKit will:

Read your configuration
Launch the browser
Execute your test steps
Generate a report

Step 5: View the Report

Open the generated HTML report in your browser to see detailed test results, including:

Pass/fail status for each step
Execution time
Screenshots (on failure)

Common Commands

Command	Description
`tkit run`	Run all tests
`tkit run --tags @smoke`	Run tests with specific tag
`tkit run --headless`	Run in headless mode
`tkit validate`	Validate configuration
`tkit init`	Initialize a new project

Next Steps

Congratulations! You've written and run your first TestFlowKit test. Continue learning:

Gherkin Basics — Learn more about writing test scenarios
Configuration — Deep dive into configuration options
Variables — Use dynamic data in your tests