Կոնտրակտային թեստեր Pact-ով
Կոնտրակտային թեստավորման շարքի երրորդ մասը։ Այս անգամ ուշադրությունը Pact-ի վրա է՝ ևս մեկ գործիք, որն օգնում է ծրագրավորողներին գրել կոնտրակտային թեստեր։ Իմացեք, թե ինչպես է այն աշխատում, ինչ առավելություններ ունի և որն է նրա հիմնական տարբերությունը Spring Cloud Contract-ից։
Սա կոնտրակտային թեստավորման շարքի երրորդ մասն է։ Նախկինում բացատրել էի, թե ինչ է կոնտրակտային թեստավորումը և ինչ օգուտներ է տալիս, իսկ հետո ներկայացրել էի Spring Cloud Contract-ը՝ նման թեստերի համար ամենալայն օգտագործվող ֆրեյմվորքներից մեկը, մասնավորապես JVM էկոհամակարգում։
Այս մասում քննարկվում է մեկ այլ տարածված գործիք, որն օգնում է ծրագրավորողներին գրել կոնտրակտային թեստեր՝ Pact ֆրեյմվորքը։ Կիմանաք, թե ինչպես է այն աշխատում, ինչ առավելություններ է առաջարկում և որն է նրա հիմնական տարբերությունը Spring Cloud Contract-ից։ Շարքն ավարտելուց հետո դուք կունենաք ամուր հիմք REST API-ի միջոցով ինտեգրված համակարգերի հաղորդակցությունը թեստավորելու համար։
Այս հոդվածի օրինակները պտտվում են order-service-ի և payment-service-ի միջև հաղորդակցության շուրջ, որը տեղի է ունենում REST API-ով։ Թեստերը գրված են Groovy-ով Spock-ի օգնությամբ, իսկ նախագծերը հավաքվում են Gradle-ով։ Հիշեցնեմ, թե ինչպես են ծառայությունները հաղորդակցվում.


Կոնտրակտի սահմանում
Spring Cloud Contract-ի դեպքում հաղորդակցության թեստավորումը սկսվում է կոնտրակտի սահմանումից։ Pact ֆրեյմվորքը ընտրում է այլ ճանապարհ։ Կոնտրակտ գրելու փոխարեն մենք սկսում ենք նկարագրելով, թե ինչ ենք ակնկալում ծառայությունների փոխազդեցություններից։ Ո՞րն է տարբերությունը։ Միակ տարբերությունն այն է, որ մեր գրածը լիովին այն փաստաթուղթը չէ, որը կիսվում է հաղորդակցվող կողմերի միջև. Pact-ը վերցնում է այդ ակնկալիքները և դրանցից գեներացնում վերջնական կոնտրակտը։ Տեսնենք, թե ինչպես դա անել Groovy-ով և Spock-ով։
class OrderCreatorPactSpec extends Specification {
(...)
def "should create order and execute online payment"() {
def accountIdVal = randomUUID()
def orderIdVal = randomUUID()
def quotaVal = BigDecimal.valueOf(1040.42)
given: 'payment-service executes online payment correctly'
def paymentService = new PactBuilder()
paymentService {
serviceConsumer "order-service"
hasPactWith "payment-service"
port 8088
uponReceiving('a request to execute online payment')
withAttributes(
method: 'PUT',
path: regexp("/payment/$UUID_REGEXP", "/payment/$orderIdVal"),
headers: [
"Accept" : APPLICATION_JSON_VALUE,
"Content-Type": APPLICATION_JSON_VALUE
]
)
withBody {
accountId uuid()
paymentType string("TRANSFER_ONLINE")
quota decimal()
dueDate datetime()
}
willRespondWith(
status: 200,
headers: ['Content-Type': APPLICATION_JSON_VALUE],
body: {
paymentExternalId("ext-$orderIdVal")
status('FINISHED')
}
)
}
when:
PactVerificationResult result = paymentService.runTest {
assert sut.createOrder(accountIdVal, orderIdVal, quotaVal, TRANSFER_ONLINE).paymentProcessed()
}
then:
result == new PactVerificationResult.Ok()
}
}
Առաջին բանը, որ պետք է նկատել, այն է, որ այս ակնկալիքները թեստի տեսքով են order-service-ում, այսինքն՝ սպառողի (consumer) կողմում։ Pact-ը աջակցում է միայն Consumer Driven Contract Testing-ին, ուստի ակնկալիքները սովորաբար գտնվում են սպառողի կողմում։
Բացի փոխազդեցությունից մեր ակնկալիքները սահմանելուց, վերը բերված թեստը նաև ստուգում է, որ սպառողը կատարում է այդ ակնկալիքները։ Մասնավորապես, թեստը կատարում է պատվերի ստեղծման տրամաբանությունը, որը ներսում օգտագործում է HTTP կլիենտ։ Ապա ‘then’ բաժնում այն ստուգում է, որ կլիենտը բավարարում է սահմանված ակնկալիքները։
Ի տարբերություն Spring Cloud Contract¹-ի՝ Pact-ը առաջին օրվանից նախագծվել է որպես տեխնոլոգիայից անկախ գործիք։ Այդ իսկ պատճառով այն առաջարկում է բազմաթիվ API-ներ և DSL-ներ տարբեր լեզուներով՝ JVM լեզուներից (Java, Groovy և այլն) մինչև Ruby, Rust և C++։ Անցնենք այս թեստի ակնկալիքներով, որոնք գրված են Groovy DSL-ով։
Ակնկալիքները գտնվում են թեստի ‘given’ բաժնում։ PactBuilder դասը տրամադրում է fluent DSL՝ հաղորդակցության կողմերը նկարագրելու համար։ Այստեղ այն սկսում է հաղորդակցվող կողմերը և պորտը նշելով, ինչը հնարավորություն է տալիս որոշել, թե որ կոնտրակտները պետք է ստուգվեն producer-ի թեստերը գործարկելիս։
serviceConsumer "order-service"
hasPactWith "payment-service"
port 8088
Հարցում
Հարցումը նկարագրում են երեք մեթոդ.
uponReceiving, որը պարզապես նշում է փոխազդեցությունների սկիզբը և թույլ է տալիս նկարագրել, թե ինչն է գործարկում այս փոխազդեցությունը, օրինակ՝uponReceiving(‘a request to execute a payment’)withAttributes, որը սահմանում է REST API endpoint-ի մեթոդը, ուղին և պարտադիր header-ներըwithBody, որը թվարկում է այն դաշտերը, որոնք հարցման մարմինը պետք է պարունակի
Ինչպես Spring Cloud Contract-ի դեպքում, մենք հնարավորության դեպքում խուսափում ենք ճշգրիտ ակնկալվող արժեքներ տալուց։ Փոխարենը դրանք նկարագրում ենք ընդհանուր օրինաչափություններով, որոնց դաշտերը պետք է համապատասխանեն։
Օրինակ՝ հարցման մարմինը չի պարունակում կոնկրետ accountId. փոխարենը այն հայտարարվում է որպես ցանկացած uuid՝ uuid()-ով։
withBody {
accountId uuid()
paymentType string("TRANSFER_ONLINE")
quota decimal()
dueDate datetime()
}
Ուղին իր հերթին նկարագրվում է կանոնավոր արտահայտությամբ.
path: regexp("/payment/$UUID_REGEXP", "/payment/$orderIdVal")
Երկրորդ արգումենտի արժեքը պետք է, որովհետև պատասխանը հղվում է դրան։ Այս կառուցվածքի շնորհիվ producer-ի թեստերը օգտագործում են տրամադրված արժեքը՝ պատահականորեն գեներացված uuid-ի փոխարեն։
Պատասխան
Վերը նկարագրված հարցման համար order-service-ը ակնկալում է, որ producer-ը կվերադարձնի որոշակի պատասխան։ Նրա կարգավիճակը պետք է լինի 200, և այն պետք է ներառի application/json արժեքով Content-Type header, ինչպես նաև երկու դաշտ՝ paymentExternalId և status։ Թեստը այս ակնկալիքները սահմանում է Groovy DSL-ի willRespondWith() մեթոդով։ Կոնտրակտը նկարագրելու համար գոյություն ունեն շատ այլ հարմար DSL մեթոդներ. մանրամասների համար տես փաստաթղթերը։
willRespondWith(
status: 200,
headers: ['Content-Type': APPLICATION_JSON_VALUE],
body: {
paymentExternalId("ext-$orderIdVal")
status('FINISHED')
}
)
Սպառողի թեստավորում
Երբ API-ի ակնկալիքները պատրաստ են, այժմ կարող ենք թեստավորել սպառողին։ Թեստը պետք է ստուգի, որ կլիենտը համապատասխանում է հաղորդակցության պահանջներին։ Pact-ով սպառողներին թեստավորելու համար պետք է ավելացնել այս կախվածությունը։
testImplementation 'au.com.dius.pact.consumer:groovy:4.4.4'
Այն պարունակում է ոչ միայն վերը նկարագրված DSL-ը, այլև API՝ թեստը Spock-ում գործարկելու համար։ Թեստը կատարում է պատվերի ստեղծման տրամաբանությունը, որը հիմքում հենվում է HTTP կլիենտի վրա, և ստուգում է, որ կլիենտը ճիշտ է կանչում payment-service-ի REST API-ն։
when:
PactVerificationResult result = paymentService.runTest {
assert sut.createOrder(accountIdVal, orderIdVal, quotaVal, TRANSFER_ONLINE).paymentProcessed()
}
then:
result == new PactVerificationResult.Ok()
Երբ հավաքում ենք order-service հավելվածը, թեստերը պետք է անցնեն։ Որպես կողմնակի արդյունք՝ Pact-ը ստեղծում է կոնտրակտը JSON ձևաչափով։ Սա իրական կոնտրակտն է, որը գեներացվել է թեստում սահմանված ակնկալիքներից, և JSON-ը օգտագործվում է սպառողին, իսկ ինչպես ցույց կտամ ավելի ուշ՝ նաև producer-ին թեստավորելու համար։ Ֆայլը կգտնեք build/pact թղթապանակում. վերը նկարագրված ակնկալիքների համար այն նման է հետևյալին (հատվածը կրճատվել է ընթեռնելիության համար)։
{
"consumer": {
"name": "order-service"
},
"interactions": [
{
"description": "a request to execute online payment",
"request": {
"body": {
"accountId": "e2490de5-5bd3-43d5-b7c4-526e33f71304",
(…)
},
"headers": {
"Accept": "application/json",
"Content-Type": "application/json"
},
"matchingRules": {
"body": {
"$.accountId": {
"combine": "AND",
"matchers": [
{
"match": "regex",
"regex": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
}
]
},
(…)
]
}
},
"method": "PUT",
"path": "/payment/f4d13515-8ffd-424a-9c71-f0a52e1ffa31"
},
"response": {
"body": {
"paymentExternalId": "ext-f4d13515-8ffd-424a-9c71-f0a52e1ffa31",
"status": "FINISHED"
},
"headers": {
"Content-Type": "application/json"
},
"status": 200
}
}
],
"provider": {
"name": "payment-service"
}
}
Producer-ի թեստավորում
Սպառողը հայտնել է իր ակնկալիքները և գեներացրել կոնտրակտը։ Հաջորդը պետք է համոզվենք, որ հաղորդակցության մյուս կողմը բավարարում է դրանք, ինչը նշանակում է, որ կոնտրակտը ինչ-որ կերպ պետք է հասնի producer-ին։ Ինչպե՞ս դա անել։
Հիմնականում երկու ճանապարհ կա.
- կոնտրակտը ինքներս հասանելի դարձնել, օրինակ՝ սերվերի վրա տեղադրված կոնտրակտի URL-ը կամ տեղական ֆայլային համակարգում նրա տեղը տալով։ Սա բավականին անհարմար մոտեցում է։
- օգտագործել Pact Broker՝ կոնտրակտները պահելու, կառավարելու և հասանելի դարձնելու գործիք։
Իմ առաջարկը Pact Broker-ն է, քանի որ այն մեծապես պարզեցնում է թեստավորումը և թողարկումը։
Pact Broker
Pact Broker-ը կարելի է դիտարկել որպես կենտրոնական տվյալների բազա, որը պահում է ծառայությունների միջև կոնտրակտները։ Այն առաջարկում է մի քանի հնարավորություն, որոնք պարզեցնում են գործընթացը.
- թույլ է տալիս թեստավորել ծառայությունները կոնտրակտի դեմ՝ ապահովելով, որ ծառայությունների կոնկրետ, թեստավորված տարբերակները կարող են անցնել արտադրություն
- տրամադրում է փաստաթղթեր և վիզուալիզացիաներ այն մասին, թե ինչպես են ծառայությունները փոխազդում
- զբաղվում է կոնտրակտների տարբերակավորմամբ և հակասությունների կառավարմամբ
Դուք կարող եք ինքներդ գործարկել, կարգավորել և կառավարել Pact Broker-ի ինստանս։ Գոյություն ունի նաև գործիքի առևտրային, լիովին կառավարվող, մասշտաբավորվող տարբերակ՝ Pact Flow։
Կոնտրակտների հրապարակում Pact Broker-ում
Կոնտրակտները Pact Broker-ում հրապարակելու համար անհրաժեշտ է Gradle plugin։ Ստորև բերված կոնֆիգուրացիան նշում է, որ broker-ը աշխատում է localhost-ի 9292 պորտում։
plugins {
id "au.com.dius.pact" version "4.3.6"
}
(...)
pact {
publish {
pactBrokerUrl = 'http://localhost:9292/'
}
}
Սրանով կոնտրակտները կարելի է հրապարակել pactPublish task-ով։
./gradlew pactPublish
order-service-ի և payment-service-ի միջև կոնտրակտներն այժմ Pact-ում են և կարելի է դիտել broker-ի GUI-ում։
Ֆայլի պատկերակին սեղմելով՝ երևում են կոնտրակտի մանրամասները։ Այն փոխազդեցությունները, որոնք սպառողի թեստերում սահմանել էինք որպես ակնկալիքներ, այստեղ հայտնվում են JSON-ի տեսքով։
Producer-ի թեստերի կատարում
Producer հավելվածը պետք է կարգավորվի այնպես, որ ճիշտ ինտեգրվի Pact Broker-ի հետ և ստուգի՝ արդյոք բավարարում է կոնտրակտի պահանջները։ Այս ծառայությունը կառուցված է Spring Boot-ով, ուստի թեստերը պետք է ինտեգրվեն դրա հետ։ Նախ ավելացնում ենք այն կախվածությունը, որը տրամադրում է API producer-ի թեստերը գործարկելու համար։
testImplementation 'au.com.dius.pact.provider:junit5spring:4.2.21'
Թեստային շարժիչը պետք է իմանա, թե որտեղ է Pact Broker-ը, ուստի դա սահմանում ենք թեստային application.properties ֆայլում։
pactbroker:
host: localhost
port: 9292
Վերջապես իրականացնում ենք թեստային դաս, որը producer-ի ստուգումները գործարկում է Pact Broker-ում հրապարակված կոնտրակտի դեմ։
@SpringBootTest(webEnvironment = RANDOM_PORT)
class ContractVerificationSpec extends Specification {
@LocalServerPort
private int port
@Shared
ProviderInfo serviceProvider
ProviderVerifier verifier
def setupSpec() {
serviceProvider = new ProviderInfo("payment-service")
serviceProvider.hasPactsFromPactBroker("http://localhost:9292")
}
def setup() {
verifier = new ProviderVerifier()
serviceProvider.port = port
}
def 'verify contract with #consumer'() {
expect:
verifyConsumerPact(consumer) instanceof VerificationResult.Ok
where:
consumer << serviceProvider.consumers
}
private VerificationResult verifyConsumerPact(ConsumerInfo consumer) {
verifier.initialiseReporters(serviceProvider)
def testResult = verifier.runVerificationForConsumer([:], serviceProvider, consumer)
if (testResult instanceof VerificationResult.Failed) {
verifier.displayFailures([testResult])
}
testResult
}
}
Կարող է բավականին բարդ թվալ, ուստի քայլ առ քայլ անցնենք, թե ինչ է տեղի ունենում։
Դասի վրա ‘@SpringBootTest’ անոտացիան ստիպում է սերվերը գործարկվել թեստային կոնֆիգուրացիայով պատահական պորտի վրա։
Հետո հայտարարում ենք երկու օբյեկտ, որոնք անհրաժեշտ են կոնտրակտի ստուգումը գործարկելու համար.
- ProviderInfo – նկարագրում է թեստավորվող ծառայության (payment-service) կոնֆիգուրացիան, ինչպիսիք են նրա անունը, host-ը, պորտը, հարցման ուղին և այլն։
- ProviderVerifier – ստուգում է producer-ին սահմանված սպառողների դեմ։
Spock-ի setup մեթոդներում provider-ը կարգավորեցինք payment-service անունով և SpringBoot-ի օգտագործած պորտով։ Նաև նշեցինք, որ կոնտրակտները գտնվում են localhost:9292 հասցեով հասանելի broker-ում։ Արդյունքում այն սպառողները, որոնք կոնտրակտ ունեն այս producer-ի հետ, broker-ից բերվում են իրենց ակնկալվող փոխազդեցություններով հանդերձ։ Սա նշանակում է, որ թեստը թարմացնել պետք չէ, երբ, ասենք, փոխազդեցությունը փոխվում է կամ նոր սպառող է ցանկանում ինտեգրվել payment-service-ի հետ։ Ամեն անգամ, երբ payment-service-ի թեստերը աշխատում են, յուրաքանչյուր սպառողի յուրաքանչյուր կոնտրակտ բերվում է Pact-ից և թեստավորվում։
Եթե հիմա հավաքեք այս հավելվածը, թեստը պետք է անցնի։ Բայց եթե API-ն չի համապատասխանում կոնտրակտի ակնկալիքներին, թեստը ձախողվում է և հաղորդում, թե ինչ է սխալ եղել։
Սա producer-ի կողմում կոնտրակտային թեստեր գործարկելու ընդամենը մեկ եղանակն է։ Ընտրել եմ այն, որովհետև այս շարքի բոլոր օրինակներն օգտագործում են Spock։ Մեկ այլ խորհուրդ տրվող տարբերակը, սակայն, producer-ի ստուգման Gradle plugin-ն է, որը կրճատում է producer-ը թեստավորելու համար անհրաժեշտ կոդը։ Այդպիսի թեստավորումը, այնուամենայնիվ, այս հոդվածի շրջանակներից դուրս է։
Pact-ը Pact Broker-ի հետ միասին օգտագործելիս լավ պրակտիկա է թեստի արդյունքները հրապարակել broker-ում։ Դա ցույց է տալիս, թե արդյոք ծառայության կոնկրետ տարբերակը բավարարում է սպառողների ակնկալիքները։ Այն միացնելու համար պետք է սահմանել երկու համակարգային հատկություն.
pact.verifier.publishResults– true արժեքի դեպքում արդյունքները հրապարակվում են broker-ումpact.provider.version– հրապարակվող ծառայության տարբերակը
test {
useJUnitPlatform()
systemProperty 'pact.provider.version', project.version
systemProperty 'pact.verifier.publishResults', 'true'
}
Այս կոնֆիգուրացիայով արդյունքները ուղարկվում են broker-ին թեստերն ավարտվելուց հետո։ Այնուհետև broker-ի GUI-ի գլխավոր էջը ցույց է տալիս, որ ծառայությունների միջև կոնտրակտը վերջերս վավերացվել է և թեստերն անցել են։
Pact Broker-ը պահպանում և ցուցադրում է տարբերակների մատրից (version matrix) յուրաքանչյուր ինտեգրացիայի համար։ Այն կարող եք բացել՝ սեղմելով կոնտրակտների ցանկում ցանցի պատկերակին։
Այն ներկայացնում է ծառայությունների միջև կոնտրակտի վավերացման պատմությունը։ Տեսնում ենք, որ 1.1.0 տարբերակը սխալ է պարունակում, ուստի այն չպետք է տեղակայվի։ Բայց ինչպե՞ս է CD pipeline-ը իմանում, թե տվյալ տարբերակը թեստավորվել է և կարող է անցնել արտադրություն։ Հենց այստեղ է գործի մտնում can-i-deploy գործիքը։ Այս CLI-ով մենք կարող ենք «հարցնել» Pact Broker-ին՝ արդյոք ծառայությունը համատեղելի է հրապարակված կոնտրակտների հետ և համապատասխանում է դրանց։ Օրինակ՝ կարող ենք ստուգել, թե payment-service-ի վերջին տարբերակը կարելի է անվտանգ տեղակայել արտադրություն։
pact-broker can-i-deploy --pacticipant payment-service --latest
‘can-i-deploy’-ը մեզ ասում է, որ այս տարբերակը լավ է։
Սակայն եթե հարցնենք 1.1.0 տարբերակի մասին, որը վերը բերված մատրիցը ցույց է տալիս որպես անհամատեղելի, կհաղորդվի ձախողում։
pact-broker can-i-deploy --pacticipant payment-service --version 1.1.0
Այս գործիքը կարելի է միացնել մեր CD pipeline-ին՝ ծառայությունների համատեղելիությունը ստուգելու համար նախքան որևէ բան արտադրություն անցնելը, ինչը պաշտպանում է մեզ անհամատեղելի ծառայությունների տարբերակներ տեղակայելուց։
Ամփոփում
Այս հոդվածում բացատրվեց, թե ինչպես է աշխատում Pact ֆրեյմվորքը։ Գրեցինք սպառողի թեստեր, որոնք հաստատում են, որ order service-ի կոդը համապատասխանում է հաղորդակցության կոնտրակտներին, և ցույց տվեցի, թե ինչպես է կոնտրակտը գեներացվում Pact-ի JSON ձևաչափով, որպեսզի կարողանա կիսվել producer-ի հետ։
Ներկայացրի նաև Pact broker-ը որպես կողմերի միջև կոնտրակտները կիսելու առաջարկվող եղանակ։ Այն հնարավորություն է տալիս producer-ի թեստերը գործարկել յուրաքանչյուր սպառողի սահմանած կոնտրակտների դեմ՝ առանց producer-ի թեստերը նույնիսկ իմանալու, թե ովքեր են այդ սպառողները։
Վերջապես ցույց տվեցի, թե ինչպես կարելի է Pact Broker-ը և ‘can-i-deploy’ գործիքը օգտագործել CD pipeline-ում՝ անհամատեղելի ծառայությունները արտադրություն տեղակայելուց խուսափելու համար։
Ընթացքում նշեցի Spring Cloud Contract-ի և Pact ֆրեյմվորքի հիմնական տարբերությունները։ Դրանցից ամենակարևորներն են.
- Pact-ը աջակցում է միայն սպառողակենտրոն (consumer-driven) մոտեցմանը, մինչդեռ Spring Cloud Contract-ը աջակցում է նաև producer-driven մոտեցմանը։
- Pact-ի կոնտրակտները լեզվից անկախ են (JSON) և գեներացվում են սպառողի թեստերից։ Spring Cloud Contract-ը պահանջում է կոնտրակտը ձեռքով գրել իր DSL-ներից մեկով։
- Spring Cloud Contract-ում կոնտրակտները պահվում են, օրինակ, Git պահոցում և կողմերի միջև կիսվում են, երբ անհրաժեշտ է, ասենք, թարմացնել։ Pact-ը գալիս է broker-ով, որը հեշտացնում է կոնտրակտների կիսումը և կառավարումը։
- Spring Cloud Contract-ը սպառողի թեստն իրականացնելու համար պահանջում է producer-ի stub, որը կառուցվում է կոնտրակտներից, որոնք սովորաբար գտնվում են producer-ի պահոցում։ Pact-ի դեպքում մենք սկսում ենք սպառողի թեստեր գրելուց, և դրանք կարելի է ավարտել առանց որևէ արտաքին stub-ի (ինտեգրացիայի ակնկալիքները թեստերի մասն են)։
- Pact-ն առաջարկում է լրացուցիչ հնարավորություններ, որոնք հեշտացնում են տեղակայման կառավարումը, օրինակ՝ can-i-deploy։
Հուսով եմ, որ այժմ դուք ունեք կոնտրակտային թեստավորման հասկացությունների հիմնական պատկերացում, ինչպես նաև որոշակի գիտելիք այս երկու ֆրեյմվորքների մասին։ Դա պետք է բավարար լինի ձեր նախագծի REST API-ների համար կոնտրակտային թեստեր գրելը սկսելու համար՝ կամ Spring Cloud Contract-ով, կամ Pact-ով։
Հաջորդ հոդվածում կքննարկվի, թե ինչպես թեստավորել իրադարձություններով վարվող (event-driven) հաղորդակցությունը Kafka broker-ների հետ։
¹Spring Cloud Contract-ն այժմ աջակցում է նաև ոչ Spring և ոչ JVM լեզուներին։