godog-example-setup

Example godog framework setup with step library gdutils

Overview:

This repository contains skeleton that allow to write End-2-End tests for HTTP API with use of framework godog that implements 🥒gherkin/cucumber syntax using step library gdutils.

Why ?

No more long and time-consuming framework setup. This project cuts initial time & allows bootstrap e2e test framework with plenty of utility methods (for testing HTTP(s) API using JSON/YAML) in just few steps. Just grab it and write tests right away.

Benefits:

• short time from setup - to writing actual E2E tests,
• 35+ well-documented, coupled in logical groups steps useful for testing HTTP(s) API,
• support for using templated values as in text/template package,
• support for querying JSON/YAML tree with different path engines (oliveagle - JSON, qjson - JSON, go-yaml - YAML),
• rich debugging possibilities - various ways to debug tests,
• very customisable (ability to replace internal services with your own implementation),
• friendly for custom steps development because of exported utility services.

Example

Click here 👆 to see more tests

Feature: Adding new user
  User's CRUD API binary and it's documentation can be found in assets/test_server/ directory.
  It is simple web server with endpoints:
  - POST    /users            - creates new user
  - GET     /users            - retrieve all users
  - GET     /users/{user_id}  - retrieve user by user_id
  - PUT     /users/{user_id}  - replace user by user_id
  - DELETE  /users/{user_id}  - delete user by user_id

  Background:
  This section runs before every Scenario.
  Its main purpose is to generate:
  - first name,
  - last name,
  - age.
  and save it under provided key in scenario cache.

    Given I save "application/json" as "CONTENT_TYPE_JSON"
    Given I generate a random word having from "5" to "10" of "russian" characters and save it as "RANDOM_FIRST_NAME"
    Given I generate a random word having from "5" to "15" of "UNICODE" characters and save it as "RANDOM_LAST_NAME"
    Given I generate a random "int" in the range from "18" to "48" and save it as "RANDOM_AGE"

  Scenario: Create user v1
  As application user
  I would like to store random user's data

    #---------------------------------------------------------------------------------------------------
    # We send HTTP(s) request using pre-generated data to create new user.
    # Accessing saved data from scenario cache is done through template syntax from text/template package.
    # Docstring may be in YAML or JSON format and should have "body" and "headers" keys.
    When I send "POST" request to "{{.MY_APP_URL}}/users" with body and headers:
    """
    {
        "body": {
            "firstName": "{{.RANDOM_FIRST_NAME}}",
            "lastName": "doe-{{.RANDOM_LAST_NAME}}",
            "age": {{.RANDOM_AGE}}
        },
        "headers": {
            "Content-Type": "{{.CONTENT_TYPE_JSON}}"
        }
    }
    """
    Then the response status code should be 201
    And the response should have header "Content-Length"
    And the response should have header "Content-Type" of value "{{.CONTENT_TYPE_JSON}}; charset=UTF-8"
    And the response body should have format "JSON"
    And time between last request and response should be less than or equal to "2s"

    # uncommenting next line will print last HTTP(s) response body to console
#    Given I print last response body

    # This waiting is unnecessary, just added for demonstration
    And I wait "2ms"

    #---------------------------------------------------------------------------------------------------
    # We validate response body with schema from assets/test_server/doc/schema/user/get_user.json
    # step argument may be: relative (see .env variable GODOG_JSON_SCHEMA_DIR) or full OS path
    And the response body should be valid according to schema "user/get_user.json"
    # or URL pointing at schema
    And the response body should be valid according to schema "https://raw.githubusercontent.com/pawelWritesCode/godog-example-setup/main/assets/test_server/doc/schema/user/get_user.json"
    # or raw schema definition passed in Docstring
    And the response body should be valid according to schema:
    """
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "title": "create user",
      "description": "Valid response from create user endpoint",
      "type": "object"
    }
    """
    # also nodes may be validated against schema
    And the "JSON" node "firstName" should be valid according to schema:
    """
    {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "first name",
        "type": "string"
    }
    """
    And the "JSON" node "firstName" should be "string" of value "{{.RANDOM_FIRST_NAME}}"
    # here is used qjson "json-path" syntax to find JSON node
    And the "JSON" node "age" should be "int" of value "{{.RANDOM_AGE}}"
    # here is used oliveagle "json-path" syntax to find JSON node
    And the "JSON" node "$.lastName" should be "string" of value "doe-{{.RANDOM_LAST_NAME}}"
    And the "JSON" node "lastName" should match regExp "doe-.*"

Documentation

See project wiki

• Overview - general information about project,
• Project structure - describes repository folder structure,
• Setup - guide how to bootstrap repository on your machine,
• Steps - describes each available step and how to use it in tests,
• Steps development - how to create custom steps using internal services,
• Usage - how to run tests.