Contract թեստավորումը գործնականում՝ Spring Cloud Contract-ով
REST API-ի contract-ի նկարագրությունը Spring Cloud Contract-ով՝ ֆրեյմվորքի հիմնական բաղադրիչները և դրա կարգավորումը։
Contract Testing-ը տեխնիկա է, որով ստուգվում է, թե ինչպես են սերվիսները խոսում միմյանց հետ, ընդ որում յուրաքանչյուր սերվիս ստուգվում է առանձին։ Այն վերացնում է այն խնդիրները, որոնք առաջանում են, երբ հաղորդակցությունը թեստավորվում է ինտեգրացիոն կամ e2e թեստերով։ Այս հոդվածում ներկայացվում է Spring Cloud Contract-ը՝ contract թեստավորման տարածված գրադարաններից մեկը։
Contract Testing-ի ընդհանուր գաղափարին ծանոթ լինելը կօգնի ավելի հեշտ հասկանալ Spring Cloud Contract-ի հիմքում ընկած հասկացությունները։
Այստեղ բոլոր օրինակները պտտվում են order-service-ի և payment-service-ի միջև REST API-ով հաղորդակցության շուրջ։ Թեստերը գրված են Groovy-ով՝ Spock-ով, իսկ երկու նախագծերն էլ կառուցվում են Gradle-ով։ Հիշեցնենք, թե ինչպես են երկու սերվիսները փոխազդում՝


Contract-ի սահմանումը
Contract-ները այս տեսակի թեստավորման կենտրոնական տարրն են։ Spring Cloud Contract-ը թույլ է տալիս դրանք նկարագրել հարմար DSL-ով (Domain Specific Language), որը կարելի է գրել Groovy-ով, Java-ով, Kotlin-ով կամ նույնիսկ YAML-ով։ Contract-ը սահմանում է, թե ինչպես են հաղորդակցվում producer-ը և նրա consumer-ները։ Ստորև բերված contract-ը նկարագրում է, թե ինչպես է order-service-ը օգտագործում payment-service-ի REST API-ը։ Այն գրված է Groovy-ով և ընդգրկում է առցանց վճարման «երջանիկ ճանապարհը» (happy path)։
Contract.make {
name "should execute online payment"
request {
method 'PUT'
urlPath $(consumer(regex('/payment/' + uuid())))
body([
accountId : $(consumer(anyUuid())),
quota : $(consumer(regex('^(\\d+\\.\\d+)$')), producer(1024.50)),
paymentType: $(consumer(regex('^TRANSFER_(OFFLINE|ONLINE)$')), producer('TRANSFER_ONLINE')),
dueDate : $(consumer(anyDateTime()))
])
headers {
accept 'application/json'
contentType 'application/json'
}
}
response {
status OK()
body([
paymentExternalId: "ext-${fromRequest().path(1)}",
status : "FINISHED",
])
headers {
contentType('application/json')
}
}
}
Contract-ների տեղը /src/contractTest/resources-ն է, որտեղ դրանք կարելի է դասավորել թղթապանակների և ենթաթղթապանակների մեջ, օրինակ՝ մեկական յուրաքանչյուր consumer-ի համար։ Այստեղ contract-ը գտնվում է payment-service/src/contractTest/resources/contracts/orderService-ում, քանի որ վերաբերում է order-service-ին։
Request
Contract-ի հիմնական մասերը request և response բլոկներն են։ Request բլոկը նշում է, թե ինչպիսին պետք է լինի API-ին կատարվող կանչը։ Այն հայտարարում է PUT մեթոդ և ճանապարհ՝ տրված որպես կանոնավոր արտահայտություն՝ /payment/, որին հաջորդում է UUID։ Այս շարահյուսությունն առաջին հայացքից կարող է մի փոքր առեղծվածային թվալ, և ես շուտով կվերադառնամ դրան։
Հաջորդը սպասվող request-ի մարմինն է՝ 4 պարտադիր դաշտով՝ accountId, quota, paymentType և dueDate։ Դրանց արժեքները կարող են բարդ թվալ, բայց մի պահից կբացատրենք։ Request բլոկի վերջին մասը թվարկում է պահանջվող header-ները՝ API-ն ակնկալում է Accept և Content-Type՝ երկուսն էլ application/json արժեքով։
Հիմնականը պարզելուց հետո բացենք այն մասերը, որոնք բաց թողեցինք, սկսելով URL-ի սահմանումից։
urlPath $(consumer(regex('/payment/' + uuid())))
$(consumer(…)) արտահայտությամբ հայտարարվում են այսպես կոչված դինամիկ հատկությունները՝ արժեքներ, որոնք չենք ուզում կոշտ ամրագրել contract-ում, ինչպիսիք են ID-ն կամ ժամանակային դրոշմը։ Դրանք կոշտ ամրագրելը consumer-ին կստիպեր իր թեստերում օգտագործել հենց այդ արժեքները, ինչը հեռու է իդեալականից։ Ուզում ենք, որ consumer թիմը ազատ լինի թեստերը գրելու իր ձևով, ուստի կանոնավոր արտահայտությունն ավելի լավ ընտրություն է։ Այստեղ մենք օգտվեցինք ներկառուցված uuid() մեթոդից, որը տալիս է UUID-ին համապատասխանող կանոնավոր արտահայտություն։
Վերևում գրածը իրականում հետևյալ արտահայտության կրճատ ձևն է՝
urlPath $(consumer(regex('/payment/' + uuid())), producer('/payment/42cc610b-575d-4a52-9fba-4a43e8d3cfe9'))
consumer()-ը նշում է, թե որ արժեքներն են ընդունվում այս API-ն կանչելիս, և հենց այդ արժեքներն են հայտնվում stub-ում։ Այստեղ ընդունվում է ցանկացած URL, որը բաղկացած է /payment/-ից և վավեր UUID-ից։ Այլ կերպ՝ consumer-ի թեստերը կարող են օգտագործել ցանկացած UUID, այլ ոչ թե մեկ կոնկրետ արժեք։
producer()-ը նշում է այն արժեքը, որն օգտագործվում է producer-ի API-ն թեստավորելիս։ Այստեղ կանոնավոր արտահայտությունը չի օգնի, քանի որ թեստը պետք է API-ն կանչի կոնկրետ URL-ով (օր.՝ /payment/42cc610b-575d-4a52-9fba-4a43e8d3cfe9)։ Քանի որ ամբողջական արտահայտությունը բավական երկար է, Spring Cloud Contract-ը թույլ է տալիս բաց թողնել producer() մասը, ինչպես արել է մեր contract-ը։ Այդ դեպքում API թեստում օգտագործվող արժեքը գեներացվում է consumer()-ում տրված կանոնավոր արտահայտությունից։
Request-ի մարմնի accountId և dueDate դաշտերը սահմանվում են նույն ձևով։ quota-ի և paymentType-ի համար մենք տվեցինք մեր սեփական կանոնավոր արտահայտությունները։
quota : $(consumer(regex('^(\\d+\\.\\d+)$')), producer(1024.50)),
paymentType: $(consumer(regex('^TRANSFER_(OFFLINE|ONLINE)$')), producer('TRANSFER_ONLINE'))
Quota-ն պետք է լինի դրական double, և ցավոք, Spring Cloud Contract-ը դրա համար ներկառուցված մեթոդ չի առաջարկում, ի տարբերություն UUID-ի։ Ներկառուցված կանոնավոր արտահայտության մեթոդների ամբողջական ցանկը գտնվում է փաստաթղթավորման մեջ։ Նույն կերպ paymentType-ը enum է, որի արժեքը կամ TRANSFER_ONLINE է, կամ TRANSFER_OFFLINE։ Ուստի կանոնավոր արտահայտությունները պետք է գրենք ինքներս և տանք արժեքը API թեստի համար (producer())։
Response
response բլոկը նկարագրում է, թե ինչ է producer-ը վերադարձնում տվյալ request-ի դիմաց։ Դրա մեծ մասը հասկանալի է առանց բացատրության՝ HTTP կարգավիճակ, response-ի մարմին և header-ներ։ Միակ բանը, որ կարող է անակնկալ լինել, paymentExternalId-ի սահմանումն է։
paymentExternalId: "ext-${fromRequest().path(1)}"
Ուզում ենք, որ այս դաշտը միշտ լինի ext- և դրան հաջորդող paymentId (որը payment-service-ը ստանում է որպես URL-ի path պարամետր)։ Քանի որ paymentId-ն սահմանված է կանոնավոր արտահայտությամբ (վավեր UUID), այն հնարավոր չէ կոշտ ամրագրել. այն պետք է լինի հենց այն արժեքը, որն ուղարկվել է URL-ում։ Այստեղ է օգնության գալիս fromRequest() մեթոդը. այն թույլ է տալիս response-ին հղվել request-ի արժեքներին։ Մեզ պետք էր paymentId-ն՝ path-ի երկրորդ հատվածը, և path(n) մեթոդը մուտք է տալիս դրան։ N-ը path-ի տարրի ինդեքսն է՝ հաշվելով 0-ից։ Նման մեթոդներ կան նաև request-ի մարմնից, header-ներից և այլն արժեքներ կարդալու համար. դրանք թվարկված են այստեղ։
Producer-ի թեստավորումը
Երբ contract-ը պատրաստ է, ուզում ենք ստուգել, թե արդյոք producer-ի API-ն իրոք վարվում է այնպես, ինչպես նկարագրված է։ Դրա համար ձեռքով թեստեր գրելու կարիք չկա. դրանք գեներացվում են contract-ներից։ Սա Spring Cloud Contract-ով աշխատեցնելու համար producer-ի նախագծին ավելացրեք հետևյալ plugin-ը և dependency-ն։
plugins {
(...)
id 'org.springframework.cloud.contract' version '4.0.0'
}
(...)
dependencies {
(...)
testImplementation 'org.springframework.cloud:spring-cloud-starter-contract-verifier:4.0.0'
}
Plugin-ն է, որ թեստեր է գեներացնում contract-ներից։ Վերևի հատվածը ենթադրում է, որ ձեր նախագիծն արդեն ունի Spring Boot հավելված գործարկելու և թեստավորելու համար անհրաժեշտ dependency-ները (օր.՝ spring-boot-starter-web և spring-boot-starter-test)։
Producer-ի թեստերը գեներացնելու և գործարկելու համար պահանջվում է Spring Cloud Contract-ի փոքր կարգավորում։
contracts {
baseClassForTests = "pl.rmaciak.payment.BaseContractTestsSpec"
testFramework = "SPOCK"
}
Նվազագույնը պետք է սահմանել միայն baseClassForTests-ը։ Երկրորդ պարամետրը ասում է, որ թեստերը պետք է գրվեն Spock-ով։ baseClassForTests-ը անվանում է այն դասը, որը ժառանգում է յուրաքանչյուր գեներացված թեստ, և այդ դասը պետք է պատրաստի թեստերի ընթացքում օգտագործվող սերվերը։ Դա անելու երկու եղանակ կա՝
- սերվերը mock անել, օրինակ՝ RestAssured-ով կամ MockMvc-ով։ Սա լռելյայն և խորհուրդ տրվող մոտեցումն է։
- սերվերը գործարկել, օրինակ՝ @SpringBootTest-ով։ Այդ դեպքում թեստերը դիմում են իրական սերվերին, այլ ոչ թե mock-ի։ Այսպես թեստավորելու համար կարգավորման մեջ testMode-ը դրեք EXPLICIT։
Մեր օրինակն օգտագործում է RestAssuredMockMvc։ Կարգավորման մնացած տարբերակները նկարագրված են այստեղ։
Ո՞ր տարբերակն ընտրել
Կարող է թվալ, թե իրական սերվերի դեմ թեստավորելը, որը լսում է request-ներ, ավելի լավ է, քան այն mock անելը։ Սակայն հիշեք, որ contract թեստավորումը հաղորդակցության մասին է, ուստի production-ի ամբողջ կոդը գործարկված լինելու կարիք չկա։
Mock արված սերվերը, որը բացահայտում է controller-ները՝ իրենց dependency-ները stub արած, սովորաբար բավարար է։ Այդ շերտն է սահմանում, թե ինչպես է աշխատում հաղորդակցությունը։ Controller-ի կանչած բիզնես տրամաբանությունը պետք չէ և կարելի է stub անել։
Թեստերը գեներացնելու և գործարկելու համար կատարեք՝
./gradlew check
Երբ API-ն համապատասխանում է contract-ին, build-ը պետք է հաջողվի։ Հակառակ դեպքում կստանաք սխալ՝ խնդրի նկարագրությամբ։
Սա հաստատում է, որ թեստերն իրոք գեներացվել և գործարկվել են։ Եկեք հիմա նայենք «կափարիչի տակ», թե ինչ է տեղի ունեցել։
Build թղթապանակի ներսում, generated-test-sources-ի տակ, կգտնեք OrderServiceSpec դասը, որը ավտոմատ գեներացվել է Spring Cloud Contract-ի կողմից։
Դասը ժառանգում է BaseContractTestsSpec-ը, որը սահմանել էինք կարգավորման մեջ, և պարունակում է Spock թեստ (նույնպես սահմանված կարգավորման մեջ), որը ստուգում է, որ սերվերը վարվում է այնպես, ինչպես contract-ն է պահանջում։ Լռելյայն գեներացված թեստը սերվերին դիմում է Spring MockMvc-ով, բայց API-ն կարելի է թեստավորել նաև հետևյալ եղանակներով՝
- SpringMockMvc Rest assured-ից։ Սա լռելյայնն է։
- SpringWebTestClient Rest Assured-ից։ Պահանջում է testMode parameter-ը դնել WebTestClient
- JaxRSClient։ Պահանջում է testMode parameter-ը դնել JaxRsClient
- Կա նաև ավելի վաղ նշված հատուկ ռեժիմը՝ EXPLICIT, որում սերվերը գործարկվում է և կատարվում են իրական HTTP կանչեր։
Ստորև բերված է մեր contract-ի համար գեներացված թեստը։ Այն կառուցում է request-ը contract-ի համաձայն, կանչում է API-ն և ստուգում, որ response-ը համապատասխանում է contract-ի սպասելիքներին։ Ոչ մի ուշագրավ բան, բացի այն, որ այս ամբողջ կաղապարային կոդը գեներացվել է մեզ համար, ուստի չենք ստիպված եղել գրել այն։ Եվ դա ընդամենը մեկ սցենար է։ Պատկերացրեք մյուսները՝ հաղորդակցության առանձին դեպքեր, սխալների դեպքեր և այլն, բազմապատկած յուրաքանչյուր endpoint-ով։ Դա մեզնից հանված բավական մեծ աշխատանք է, այնպես չէ՞։
def validate_should_execute_online_payment() throws Exception {
given:
MockMvcRequestSpecification request = given()
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body('''{"accountId":"f4459572-b7a8-4d2e-9f49-75009f9e7f6f","quota":1024.50,"paymentType":"TRANSFER_ONLINE","dueDate":"2018-08-18T12:23:34"}''')
when:
ResponseOptions response = given().spec(request)
.put("/payment/5ecbe91f-a1f7-baff-a9b3-55d48cbbf2fb")
then:
response.statusCode() == 200
response.header("Content-Type") ==~ java.util.regex.Pattern.compile('application/json.*')
and:
DocumentContext parsedJson = JsonPath.parse(response.body.asString())
assertThatJson(parsedJson).field("['paymentExternalId']").matches("ext-5ecbe91f-a1f7-baff-a9b3-55d48cbbf2fb")
assertThatJson(parsedJson).field("['status']").isEqualTo("FAILED")
}
Նման թեստերը (սովորաբար ավելի շատ սցենարներ ընդգրկելով) ստուգում են, որ API-ն ճիշտ է։ Հաջորդ քայլը այն ստուգելն է, որ consumer-ը այս API-ն կանչում է ճիշտ։
Consumer-ի թեստավորումը
Consumer սերվիսի թիմը պետք է գրի թեստեր, որոնք հաստատում են, որ իրենց սերվիսը ճիշտ է ինտեգրվում API-ին։ Այս թեստերը կարող են աշխատել տարբեր մակարդակներում. կարող են ընդգրկել միայն HTTP client-ը, կամ կարող են ստուգել, որ սերվիսի տրամաբանությունը ճիշտ է վարվում մյուս սերվիսի հետ փոխազդելիս, ինչը, ըստ էության, ինտեգրացիոն թեստերն են անում։ Հիմնական տարբերությունն այն է, որ Spring Cloud Contract-ով stub-երը մենք ինքներս չենք գրում։ Փոխարենը օգտագործում ենք producer-ի contract-ից գեներացվածները։
Եթե նորից նայենք payment-service-ի build թղթապանակին, կնկատեք ևս մեկ JAR ֆայլ՝ payment-service-0.0.0.1-SNAPSHOT-stubs.jar
Այս JAR-ը պարունակում է stub-երը և կարող է օգտագործվել consumer-ի թեստերում WireMock սերվեր գործարկելու համար։ Դրանով զբաղվում է Spring Cloud Contract Stub Runner-ը։
testImplementation 'org.springframework.cloud:spring-cloud-starter-contract-stub-runner:4.0.0'
Այն տրամադրում է AutoConfigureStubRunner անոտացիան, որն ընդունում է մի քանի արգումենտ։ Ամենապարզ կարգավորման դեպքում պահանջվում է միայն ids պարամետրը։ Այն նշում է, թե որ stub JAR-ներն օգտագործի Wiremock-ը սերվերը mock անելու համար։
@SpringBootTest(classes = [OrderApplication])
@AutoConfigureStubRunner(
ids = ["com.rmaciak:payment-service:0.0.1-SNAPSHOT:stubs:8088"],
stubsMode = StubRunnerProperties.StubsMode.LOCAL
)
class OrderCreatorWithContractSpec extends Specification {
(...)
}
Այստեղ ես մատնանշեցի payment-service-ի contract-ներից կառուցված JAR-ը։ Զանգվածի ներսի տողն առաջին հայացքից կարող է տարօրինակ թվալ, ուստի եկեք բաժանենք մասերի։
- առաջին հատվածը groupId-ն է
- payment-service-ը artifactId-ն է
- 0.0.0.1-SNAPSHOT – stub JAR-ի տարբերակը։ Կարող է լինել ‘+’, որը նշանակում է՝ միշտ օգտագործվում է վերջին տարբերակը
- stubs-ը JAR-ի classifier-ն է։ Սա լռելյայն արժեքն է և կարելի է բաց թողնել։
- 8088-ը այն պորտն է, որը լսում է WireMock սերվերը։ Եթե չտրվի, ընտրվում է պատահականը։
Օրինակում օգտագործված AutoConfigureStubRunner-ի մյուս պարամետրը stubsMode-ն է։
Այն ընդունում է այս արժեքները՝
- LOCAL – stub-երը բեռնվում են տեղային պահոցից (օր.՝ Maven-ի /.m2 թղթապանակից), որը պետք է կարգավորված լինի ձեր build գործիքի կողմից։ Այստեղ ես օգտագործեցի Maven։
- REMOTE – stub-երը բեռնվում են հեռավոր պահոցից։ Այս ռեժիմում հեռավոր պահոցը պետք է նշվի repositoryRoot պարամետրով։
- CLASSPATH – classpath-ը սկանավորվում է սահմանված stub-երի համար։ Սա լռելյայնն է։
Անոտացիայի մյուս պարամետրերը թվարկված են փաստաթղթավորման մեջ։
Երբ stub-երը աշխատում են, կարող ենք թեստավորել այն կոդը, որը HTTP կանչ է անում մյուս սերվիսին։
def "should create order and initiate offline payment"() {
given:
def accountId = randomUUID()
def orderId = randomUUID()
def quota = BigDecimal.valueOf(120.99)
expect:
sut.createOrder(accountId, orderId, quota, TRANSFER_OFFLINE).paymentProcessed()
}
Նկատեք, որ այստեղ այլ stub չի կարգավորված. Stub Runner-ը ամեն ինչ հոգում է ինքը։
Այս պահին և՛ producer-ը, և՛ consumer-ը թեստավորված են համաձայնեցված contract-ի դեմ։ Երբ երկու սերվիսների թեստերն էլ անցնում են CI/CD pipeline-ում, կարող ենք վստահ լինել, որ դրանք ճիշտ են ինտեգրված և ապահով կերպով ուղարկել production։
Բնականաբար, այս հոդվածը որպես օրինակ ցույց է տալիս ընդամենը մեկ contract։ Ճիշտ անելու համար հավանաբար ավելի շատ contract-ներ կպահանջվեն, օրինակ՝ երբ բացառիկ դեպքերի համար, ինչպիսիք սխալներն են, կան առանձնահատուկ response-ներ։ Այնուամենայնիվ, հիշեք այն թակարդը, որի մեջ contract թեստավորումը կարող է ձեզ գցել։
Հաջորդը տեսնենք, թե ինչպես է Spring Cloud Contract-ը աշխատում և՛ Consumer Driven, և՛ Producer Driven մոտեցումների հետ։
Consumer-Driven Contract թեստավորում Spring Cloud Contract-ով
Հիշեցնենք, որ Consumer Driven Contract մոտեցման դեպքում consumer-ը՝ upstream սերվիսը, սահմանում է հաղորդակցությունը։ Producer սերվիսի (downstream) տերը թիմը պետք է կառուցի API-ն այնպես, ինչպես խնդրել է consumer-ը (կիրառելով առողջ դատողություն)։ Ահա օրինակ, թե ինչպես կարող է աշխատել consumer թիմը։
Spring Cloud Contract-ը աջակցում է այս աշխատանքային հոսքին։ Երբ consumer թիմը գոհ է contract-ից, նրանք գեներացնում են թեստերը (3) և stub-երը (5)։ Այնուհետև կարող են վերցնել գեներացված JAR-ը stub-երով և ներառել իրենց նախագծում, ինչպես աշխատում է լռելյայն stubsMode-ը (CLASSPATH)։ Սակայն ավելի լավ տարբերակ է դրանք հրապարակել տեղային պահոցում, օրինակ՝ Maven-ինում (.m2), և օգտագործել consumer-ի թեստերում. հենց դա է անում LOCAL stubsMode-ը։
Սա պետք է լինի միայն ժամանակավոր լուծում, մինչև producer թիմը կառուցի API-ն։ Երբ դա արվի և բոլոր թեստերն անցնեն, stub JAR-ը պետք է հրապարակվի հեռավոր (գլոբալ) Artifactory-ում։ Այդ դեպքում consumer թիմը կարող է stubsMode-ը փոխել REMOTE, որպեսզի stub-երը միշտ բեռնվեն Artifactory-ից։ Սա համադրեք stub-ի տարբերակը վերջինին դնելու հետ (+ ids-ում)։ Այդժամ consumer-ի թեստերը աշխատում են այն stub-երի դեմ, որոնք արտացոլում են producer-ի հետ համաձայնեցված contract-ը, ինչը դրանք վստահելի է դարձնում։
Producer Driven Contract թեստավորում Spring Cloud Contract-ով
Spring Cloud Contract-ը Producer Driven Contract Testing-ի համար հատուկ աջակցություն չունի։ Այս մոտեցման դեպքում producer-ը տիրապետում է contract-ներին, իսկ consumer-ները պարզապես ընդունում են դրանք՝ առանց խոսքի իրավունքի։ Ուստի payment թիմը պետք է գրի contract-ը և կառուցի API-ն դրան համապատասխան։ Դրանից հետո stub-երը կարելի է գեներացնել և հանձնել consumer-ներին՝ իրենց թեստերում օգտագործելու համար։ Ինչպես դրանք կիսվեն, կախված է հանգամանքներից՝ Artifactory, Nexus, Git պահոց և այլն։ Ինտեգրացիոն թեստավորումը հնարավոր դարձնելուց բացի, stub-երը նաև ծառայում են որպես փաստաթղթավորման ձև այն մասին, թե ինչպես է վարվում producer-ի API-ն։
Ամփոփում
Այս հոդվածը ցույց տվեց, թե ինչպես նկարագրել REST API-ի contract-ը Spring Cloud Contract-ով և ինչպես դրա դեմ թեստավորել և՛ producer-ը, և՛ consumer-ը։ Ընթացքում դուք ծանոթացաք ֆրեյմվորքի հիմնական բաղադրիչներին և նրա հիմնական կարգավորմանը։ Ես նաև ներկայացրի Spring Cloud Contract-ը contract թեստավորման համար օգտագործելու երկու եղանակ՝ Consumer Driven և Producer Driven։
Այս հոդվածը կարդալուց հետո դուք պետք է պատրաստ լինեք Spring Cloud Contract-ը ներդնել ձեր սեփական նախագծում։