DSL domain specific language of Kola

How we design Kola - ApiHugKola background, Kola a consumer driver tester frameworkhttps://apihug.com/zhCN-docs/kola/003_dsl_contract

Concept

在 Kola 定位中 Kola 是什么, 是致力于提供一个让相关各方都能够理解共同创造的测试框架和工具。

同时 Kola 是建立于业界成熟的实践和方法论上，综合工程实践的便利和流程的严谨性，在主流的测试思想中，这三种 Kola 深受启发：

TDD: Test driven development
BDD: Behaviour-Driven Development
CDC: Consumer Driven Contracts

在工程实践中; Kola 从 SmartBear 的 PactFlow, Spring clout Contract, Spock, Karate 等前辈上得到很多参考和灵感；

更不用说，测试界的基石: Junit5, TestNG, AssertJ 等基础框架；

Kola 一如既往遵循软件开发的开闭原则，在学习成本、工程实践、团队协同上做综合的调和，让整个测试过程更丝滑，更人性化:

Kola make your test life happier and colourful

为什么 BDD 风格声明为首选？虽然我们没有使用主流 BDD 实践框架比如 Cucumber, 作为底座；

但是 BDD 的表达方式，真的是太好了，兼顾程序世界的结构化，和非程序世界的通俗易懂；所以用他来表达用户用例(故事)再好不过！

Feature: Explaining ApiHug
  In order to gain an understanding of the ApiHug testing system
  As a non-programmer
  I want to have an overview of ApiHug that is understandable by non-geeks

  Scenario: A worker seeks an overview of ApiHug 
    Given I have a coworker who knows a lot about ApiHug
    When I ask my coworker to give an overview of how ApiHug works
    And I listen to their explanation
    Then I should have a basic understanding of ApiHug

这个来自官方的标准BDD 定义方式，在 Kola 概念基本暴利，除了 And 被省掉；

因为一般我们是 request, response 方式验证API, And 就是发送请求， Then 直接对结果验证。

Kola, 协议定义在: import hope.kola.contract.Feature 使用 groovy 语法，让整体的用例书写更轻松和愉悦。

👍 如果你的 Feature Groovy 在IDE未能识别，在更新版本后尝试 Reload gradle 以让IDE刷新识别。

Background

A Background allows you to add some context to the scenarios that follow it. It can contain one or more Given steps, which are run before each scenario, but after any Before hooks.

Feature

The purpose of the Feature keyword is to provide a high-level description of a software feature, and to group related scenarios.

Scenario

a written description of your product’s behavior from one or more users’ perspectives

Given

Given steps are used to describe the initial context of the system - the scene of the scenario. It is typically something that happened in the past.

在 ApiHug 上下文， Given 就是 API 环境，可以从 ApiHug 或者独立的API 环境引入：

ApiHug API

这个是最直接的方式：

    Given {
        api("UserService", "Login")
    }

UserService ApiHug 服务, 最好全路径引入，编译时会校验，相对路径也可以，但是保证无重复， IDEA 提供工具自动化完成
Login 方法名，在此服务内必须包含

直接用 ApiHug 上下文的 api 可以有更丰富的上下文，关于request, response 的定义， path, 参数，校验规则。

request body 预 mock, 无须自己写 body, 只需稍微调整就可以。

是 kola 首推的方式！

Raw API

如果第三方的API，我们没有的元信息，只能通过手动写：

    Given {
        get("https://github.com")
    }

When

When steps are used to describe an event, or an action. This can be a person interacting with the system, or it can be an event triggered by another system.

在 ApiHug 的定义中， When 用来组装 request 的上下文：

类型	备注
`body`	请求体，可以通过json, 然后通过生命式语法动态声明
`multipart`	附件
`cookies`	cookie 信息
`headers`	header 信息
`queries`	请求参数(动态)
`paths`	路径参数(动态)

请求体

JSON 定义:

    json("""
{
   "name": "jake",
   "age": 18,
   "address": {
     "country": "$V('from')",
     "zip": 200021
   }
}
""")

标准 json 定义方式
动态环境变量 $V('from') 运行时会通过 expression 从环境中获取 from 参数值；

body 修改:

定义完成后如果还不能满足需求，可以继续通过 body 进行 json path 进一步修改, 修改和覆盖原来值;

  body {
      set('name', "same")
      set('student.name', "blue")
      set('student.age', 22)
      set('student.weight', 123.3d)
      set('student.friends', "jake", "blue", "yellow")
      fromGlobal("student.country", "country")
  }

最终组装成一个合适的请求体；

multipart

  multipart {
      file{
        fromClassPath("hello.txt")
      }
  }

cookies

    cookies {
        //Possible Bear + {jwt}
        fromGlobal(authorization(), "jwt")
    }

headers

queries

  queries {
      pageable {
          page(0)
          size(12)
      }
      fromGlobal("userName", "jake")
  }

paths

  paths {
      fromGlobal("user-id", "userId")
  }

Then

Then steps are used to describe an expected outcome, or result.

status

  Then {
      isOk()
      status 200
  }

body

    stringAssert("user.address.zipCode", {
        isEqualTo("jake")
        isBase64()
        isAlphabetic()
        startsWithIgnoringCase("json")
    })
    bigDecimalAssert("user.salary", {
        isCloseTo(new BigDecimal("1112.22"), Offset.offset(12))
        isGreaterThanOrEqualTo(new BigDecimal("231312"))
    })
    booleanAssert("user.live", {
        isTrue()
    })

基于 json path
Assertj Assertions 全部 bridge, Fluent assertions
声明式校验，一写到底，一气呵成

Script Support

Pre Script

Post Script

    postScript {
        {
            headSet("age", 1234)
            globalSet("same", "blue")
        }
    }

Junit

Consumer Driven Contracts, What’s Kola’s domain language looks like?

How it easy to understand and get hand in. you will love it.

Default Extension, lifecycle management.

Configuration

Use DSL to define environment also {WIRE_MODULE}/src/test/resources/config/kola.groovy:

common: base configuration
different env overwrite configuration property
active env base on the passed env flag: -Dtags=qa,dev

import com.test.bigger.example.Student
import static hope.kola.contract.Configuration.*

var big = 1123

[
        common {
            baseURI("https://qa.example.com")
            port(9527)
            p("date", ofDate("2022-12-12"))
            rest {
                log {
                    enablePrettyPrinting()
                    logBodyDetailIfValidationFails()
                }
            }

        },

        env("qa", {

            baseURI("https://qa.example.com")
            port(big)

        }),

        env("prod", {

            baseURI("https://prod.example.com")
            p("date", nowDayOfMonth())
            p("bigStudent", new Student().setName("jake").setAge(19))
            rest {
                closeIdleConnectionsAfterEachResponse(12l, second())
                log {
                    logAllDetailIfValidationFails()
                }
            }
        })
]

Sample

import hope.kola.contract.Feature
import org.assertj.core.data.Offset

Feature.make {
    priority 100
    name("Customer login place order and check balance logic")
    description("""Never judge the boss, as you may the real fool""")
    Scenario "001 Try login ", {
        preScript {
            //Define prepare logic here
        }
        Given {
            api("UserService", "Login")
        }
        When {
            json("""
                    
            """)
            body {
                set('name', "same")
                set('student.name', "blue")
                set('student.age', 22)
                set('student.weight', 123.3d)
                set('student.friends', "jake", "blue", "yellow")
                fromGlobal("student.country", "country")
            }
            queries {
                pageable {
                    page(0)
                    size(12)
                }
                fromGlobal("userName", "jake")
            }
            paths {
                fromGlobal("user-id", "userId")
            }
        }
        And {
            stringAssert("user.address.zipCode", {
                isEqualTo("jake")
                isBase64()
                isAlphabetic()
                startsWithIgnoringCase("json")
            })
            bigDecimalAssert("user.salary", {
                isCloseTo(new BigDecimal("1112.22"), Offset.offset(12))
                isGreaterThanOrEqualTo(new BigDecimal("231312"))
            })
            booleanAssert("user.live", {
                isTrue()
            })

        }
        postScript {
            {
                headSet("age", 1234)
                globalSet("same", "blue")
            }
        }

    }
    Scenario "002 Place a order", {}
    Scenario "003 Check balance", {}
}