VPS पर API mocking और testing कैसे सेटअप करें
VPS पर WireMock और Hurl का उपयोग करके API टेस्टिंग को कैसे व्यवस्थित करें। अपनी CI पाइपलाइन में स्टब्स और टेस्ट रनर्स को एक साथ चलाने का सही तरीका और इसके लाभ जानें।
एक ही repository साझा करने वाले दो कार्य
Self-hosted API mocking और testing दो अलग-अलग कार्य हैं, और इन्हें एक ही मानने में एक सप्ताह बर्बाद हो जाता है। एक mock server उस dependency का स्थान लेता है जिसे आप CI से call नहीं कर सकते: जैसे कि payment provider, partner API, rate limited upstream, या ऐसी service जिसे किसी अन्य टीम ने अभी तक ship नहीं किया है। एक API test runner आपके स्वयं के endpoints को एक निश्चित क्रम में call करता है और responses की पुष्टि (assert) करता है, जिसमें एक response से मान (values) लेकर अगले request में उपयोग किए जाते हैं।
कुछ tools दोनों कार्य करते हैं। एक mock server का मुख्य कार्य requests का उत्तर देना है। एक test runner की इस बात पर कोई राय नहीं होती कि कार्ड decline होने पर payment provider क्या return करता है। अधिकांश टीमें जो पहले से ही एक box किराए पर लेती हैं, वे अंततः दोनों में से एक-एक चलाती हैं, जिन्हें एक ही Docker Compose file द्वारा start किया जाता है और एक ही pull request में review किया जाता है।
API mocking और testing को self-host क्यों करें?
आपके fixtures production के अनुरूप डेटा होते हैं। API test में request body एक वास्तविक customer record होती है, जिसमें नाम बदल दिया जाता है, या फिर नाम नहीं बदला जाता क्योंकि किसी ने जाँच नहीं की। Recorded stubs और भी खराब होते हैं: proxy recording वह सब कुछ store कर लेती है जो upstream ने वास्तव में return किया था। इसलिए, recording द्वारा बनाई गई stub directory में live tokens और customer email addresses तब तक रहते हैं जब तक कोई हर एक file को न पढ़ ले। किसी hosted service पर वह डेटा किसी और की incident और आपकी disclosure बन जाता है।
दूसरा कारण reachability है। private address से bind किसी service को hosted runner द्वारा access करने के लिए private network connection की आवश्यकता होती है। हर workaround की अपनी कीमत होती है। test करने के लिए API को internet पर publish करना उस कारण को ही खत्म कर देता है जिसके लिए वह private थी। tunnel या public staging copy एक और system है जिसे maintain करना पड़ता है, और staging copy releases के बीच production से अलग (drift) हो जाती है। GitHub-hosted runners WireGuard overlay या Azure Virtual Network के माध्यम से private access का समर्थन भी करते हैं। उसी private network पर मौजूद एक runner service को सीधे call करता है और उसे इनमें से किसी की आवश्यकता नहीं होती, जो self-hosted GitHub Actions runner के पीछे का व्यावहारिक तर्क है।
आपको कौन सा self-hosted mock server चलाना चाहिए?
इनमें से प्रत्येक आपके द्वारा नियंत्रित सर्वर पर एक container के रूप में चलता है। सबसे महत्वपूर्ण प्रश्न यह है कि प्रत्येक tool किसे 'source of truth' मानता है, क्योंकि इसी से तय होता है कि container को फिर से बनाने में आपको कोई मेहनत नहीं करनी पड़ेगी या फिर पूरा दोपहर बर्बाद होगा।
- WireMock प्रत्येक stub को
mappings/directory में एक JSON file के रूप में रखता है, और बड़े response bodies को__files/में रखता है। इसका imagewiremock/wiremockहै, container के अंदर इसकी root directory/home/wiremockहै, और यह एक recording proxy के रूप में भी चलता है। डिस्क पर फाइलें होने का मतलब है कि mock किसी अन्य code की तरह ही git में रहता है। - Mockoon CLI पूरे mock API को एक ही JSON data file में रखता है। इसे
npm install -g @mockoon/cliसे install करें औरmockoon-cli start --data ./data-file.jsonसे start करें, या उस file को bind mount करकेmockoon/cliimage चलाएं। desktop app उसी file को edit करता है, इसलिए UI में design करना और परिणाम को commit करना आपस में compatible रहता है। - MockServer
mockserver/mockserverimage से चलता है और port 1080 पर listen करता है। Expectations इसके अपने REST API के माध्यम से आती हैं, जो test code के लिए तो सुविधाजनक है लेकिन deployment के लिए जोखिम भरा है: डिफ़ॉल्ट रूप से, HTTP call द्वारा बनाई गई expectation container restart होने पर हट जाती है। उन stubs के लिए इसके JSON initialization file का उपयोग करें जिन्हें स्थायी रखना है। Runtime बदलावों को बनाए रखने के लिए,persistExpectationsसक्षम करें, output file को container के बाहर persist करें, और startup पर इसेinitializationJsonPathके माध्यम से load करें। - Prism अलग stub files के बजाय आपके OpenAPI document से mock बनाता है। इसे
npm install -g @stoplight/prism-cliसे install करें, फिरprism mock openapi.yamlचलाएं। container के अंदर-h 0.0.0.0जोड़ें, क्योंकि Prism डिफ़ॉल्ट रूप से localhost पर bind होता है और अन्यथा container के बाहर से पहुंच योग्य नहीं होता है। - Microcks एक बड़ा विकल्प है: यह एक web UI है जो OpenAPI documents और Postman collections को import करता है, फिर उन्हें mocks के रूप में serve करता है और contract tests चलाता है। पूर्ण install के लिए MongoDB और Keycloak की आवश्यकता होती है, साथ ही इसके async features के लिए Kafka भी चाहिए। all-in-one
microcks-uberimage में एक in-memory MongoDB शामिल है, जिसे project documentation के अनुसार केवल अस्थायी उपयोग के लिए उपयुक्त माना गया है, इसलिए UI में बनाई गई किसी भी चीज़ को disposable मानें और source artifacts को git में रखें।
आपको कौन सा self-hosted API test runner चलाना चाहिए?
यहाँ कार्य एक क्रम है: authenticate करना, order बनाना, उसे वापस पढ़ना, और यह सुनिश्चित करना कि state बदल गई है। इसके लिए एक response से value capture करके उसे अगले request में उपयोग करने की आवश्यकता होती है। जो tool calls के बीच state को बनाए नहीं रख सकता, वह केवल health check है, API test नहीं।
- Hurl एक single binary से HTTP requests की plain text files चलाता है। एक
[Captures]section response से values निकालता है, एक[Asserts]section उनकी जाँच करता है, और--testइसे summary और exit code के साथ एक test runner में बदल देता है। अगस्त 2026 तक version 8.0.1 current है। - Bruno CLI
.brufiles के एक folder को चलाता है।npm install -g @usebruno/cliके साथ install करें, फिरbru run folder --env Local --reporter-junit results.xmlचलाएँ। collection format को design के अनुसार directory में text files रखा गया है, इसलिए review में diffs पढ़ने योग्य होते हैं। - Newman Postman collections को Postman के बाहर चलाता है:
npm install -g newman, फिरnewman run collection.json -r cli,junit --reporter-junit-export results.xml। इसमें समस्या format की है। Newman exported collections को v2.1 JSON format में चलाता है। Postman अब v3 collection format और Postman CLI के माध्यम से Native Git workflows को भी support करता है। Postman के docs का कहना है कि Newman को आगे कोई updates या fixes नहीं मिलेंगे और वे scripts तथा CI pipelines को Postman CLI पर migrate करने की सलाह देते हैं। - Schemathesis एक अलग प्रकार की जाँच है। यह एक OpenAPI schema को पढ़ता है और ऐसे cases generate करता है जो उन responses को produce करने की कोशिश करते हैं जिन्हें आपका schema असंभव बताता है:
uvx schemathesis run https://your.api/openapi.json। यह crashes और contract violations ढूँढता है, और यह आपके business rules के बारे में कुछ नहीं जानता, इसलिए यह scripted suite को replace करने के बजाय उसके साथ काम करता है। - Hoppscotch self-hosted एक web UI विकल्प है, और इसके लिए Postgres instance की आवश्यकता होती है। इसे install करने से पहले इस tradeoff को समझें: collections repository में नहीं, बल्कि database में रहती हैं।
एक जिसे avoid करना चाहिए। Step CI अभी भी tool roundups में दिखाई देता है और इसका YAML workflow format पढ़ने में अच्छा लगता है, लेकिन repository में आखिरी commit अगस्त 2024 में हुआ था। जो program आपके CI और API के बीच स्थित हो, वहाँ unmaintained code रखना जोखिम भरा है।
Mock server को firewall के पीछे रखें
नीचे दिया गया सेटअप एक payment provider के विकल्प के रूप में WireMock को चलाता है। यदि compose file format आपके लिए नया है, तो Docker Compose on a VPS उन lifecycle commands को कवर करता है जिन्हें यह सेक्शन आधार मानता है।
services:
mock-payments:
image: wiremock/wiremock:3.13.2
command: ["--verbose"]
volumes:
- ./mocks/payments:/home/wiremock
ports:
- "127.0.0.1:8080:8080"
restart: unless-stoppedपोर्ट पर 127.0.0.1: prefix सबसे महत्वपूर्ण हिस्सा है। एक साधारण 8080:8080 mock को हर interface पर publish कर देता है, जिसमें आपका public IP भी शामिल है। यह तब भी reachable रहता है जब ufw उस port को deny कर रहा हो, क्योंकि Docker, ufw के INPUT rules तक पहुँचने से पहले ही traffic को nat table के माध्यम से route कर देता है। Engine 28.0.0 या उसके बाद के संस्करणों पर Docker के default bridge networking के साथ, published port को केवल host से ही सुलभ रखने के लिए इसे loopback address पर bind करें। पुराने releases में, एक ही layer 2 network पर मौजूद hosts, localhost पर published ports तक पहुँच सकते हैं। किसी private interface address पर bind करने से भी उन networks से access मिलता है जो उस address तक route कर सकते हैं।
आपका service under test फिर mock की ओर point करता है। जब service एक ही compose project में चलती है, तो mock का base URL http://mock-payments:8080 होता है, क्योंकि compose अपने network पर service names को resolve करता है। जब service host पर चलती है, तो यह http://127.0.0.1:8080 होता है। इसे environment variable के माध्यम से set करें, कभी भी code में न लिखें, अन्यथा test URL production में चला जाएगा।
Stubs को ./mocks/payments/mappings/ में रखें, प्रत्येक के लिए एक JSON file।
{
"request": {
"method": "POST",
"urlPath": "/v1/charges",
"bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
},
"response": {
"status": 201,
"headers": { "Content-Type": "application/json" },
"jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
}
}इसे start करें, फिर जाँचें कि वास्तव में क्या load हुआ है।
docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings--wait तब तक block करता है जब तक container healthy न हो जाए। यह इसलिए काम करता है क्योंकि WireMock image अपने /__admin/health endpoint के विरुद्ध एक HEALTHCHECK के साथ आती है। mappings call उन सभी stubs को list करती है जिन्हें server ने read किया है। यदि आपके द्वारा लिखा गया कोई stub उस list में नहीं है, तो वह load नहीं हुआ है: जाँचें कि file mounted root के बजाय mappings/ के अंतर्गत है, और यह भी कि JSON सही ढंग से parse हो रहा है।
जब कोई request आती है और कोई stub match नहीं होता, तो WireMock 404 उत्तर देता है। यदि उसे कोई near match मिलता है, तो body Request was not matched से शुरू होती है, जिसके बाद सबसे करीबी stub के साथ एक diff होता है। यदि कोई stub mappings न हों, तो body No response could be served as there are no stub mappings in this WireMock instance. होती है। कुछ भी बदलने से पहले diff को पढ़ें, क्योंकि यह उस सटीक field का नाम बताता है जो भिन्न है। यह आमतौर पर एक path होता है जहाँ /v1/charge लिखा होता है, जबकि stub में /v1/charges होना चाहिए।
टेस्ट को एक अनुक्रम के रूप में लिखें जिसमें कॉल्स के बीच स्टेट बनी रहे
Hurl फाइलें प्लेन टेक्स्ट होती हैं। प्रोजेक्ट के releases से deb फाइल इंस्टॉल करें।
VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.debएक सूट जो आपके अपने API को mock के विरुद्ध टेस्ट करता है, वह tests/checkout.hurl में स्थित है।
POST {{base_url}}/orders
Content-Type: application/json
{
"sku": "ssd-1tb",
"amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"
GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"[Captures] ब्लॉक ही वह हिस्सा है जो इसे दो असंबंधित अनुरोधों के बजाय एक API टेस्ट बनाता है। order_id को पहले रिस्पॉन्स से पढ़ा जाता है और दूसरे के URL में इंटरपोलेट किया जाता है। charge_id पर किया गया assertion ही पूरी प्रक्रिया का मुख्य बिंदु है: यह साबित करता है कि आपकी सर्विस ने पेमेंट प्रोवाइडर को कॉल किया और जो रिस्पॉन्स आया उसे स्टोर किया, और जिस वैल्यू से इसकी तुलना की जा रही है, वह वही है जिसे आपने WireMock स्टब में लिखा था। अब एक ही फाइल फ्लो के दोनों हिस्सों को कवर करती है।
hurl --test --variable base_url=http://127.0.0.1:3000 \
--report-junit reports/junit.xml \
--report-json reports/json \
tests/एक सफल रन प्रत्येक फाइल के लिए एक लाइन और एक सारांश प्रिंट करता है।
tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files: 1
Executed requests: 2 (30.1/s)
Succeeded files: 1 (100.0%)
Failed files: 0 (0.0%)
Duration: 64 msएक विफलता फाइल और लाइन नंबर के साथ error: Assert failure प्रिंट करती है, फिर वह वैल्यू जो प्राप्त हुई और जो अपेक्षित थी, और hurl नॉन-जीरो एग्जिट कोड देता है ताकि CI रुक जाए। यदि status में pending पढ़ा जाता है जहाँ आपको paid की अपेक्षा थी, तो आपकी सर्विस ने mock के रिस्पॉन्स को प्रोसेस नहीं किया। इसके बाद अगला कदम /__admin/requests पर WireMock रिक्वेस्ट जर्नल को पढ़ना है, जो यह दिखाता है कि क्या कॉल वास्तव में mock तक पहुँची थी।
अपने स्वयं के CI runner से suite को ट्रिगर करें
उसी मशीन पर पंजीकृत runner के साथ, workflow संक्षिप्त रहता है। runner host पर एक सामान्य process है, इसलिए उस host पर docker और hurl का इंस्टॉल होना अनिवार्य है। hosted image से कुछ भी inherit नहीं होता है।
name: api-tests
on: [push]
jobs:
hurl:
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
- name: Start the mock
run: docker compose up -d --wait mock-payments
- name: Run the suite
run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
- name: Archive the reports
if: always()
run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
- name: Stop the mock
if: always()
run: docker compose downarchive step पर if: always() महत्वपूर्ण है। इसके बिना, एक failed test run copy को छोड़ देता है, जिससे आप वह report खो देते हैं जिसे आप पढ़ना चाहते थे। copy को workspace के बाहर भी होना चाहिए, क्योंकि actions/checkout@v4 fetch करने से पहले डिफ़ॉल्ट रूप से git clean -ffdx चलाता है, जो अगली checkout पर repository directory से untracked reports को हटा देता है।
केवल अंतिम रन ही नहीं, बल्कि परिणाम भी सुरक्षित रखें
प्रति commit एक JUnit XML फ़ाइल केवल एक प्रश्न का उत्तर देती है: क्या यह पास हुआ। यह इस प्रश्न का उत्तर नहीं देती कि कोई endpoint कब धीमा होना शुरू हुआ, क्योंकि एक बार फ़ाइलें बंद करने के बाद उन्हें कोई नहीं पढ़ता। रुझान (trend) देखने के लिए, उसी मशीन पर एक छोटे डेटाबेस में प्रति रन एक पंक्ति जोड़ें। एक एकल table जिसमें commit SHA, फ़ाइल का नाम, पास काउंट, फेल काउंट और अवधि हो, पर्याप्त है, और VPS पर SQLite का उपयोग इसे रखने के लिए एक उचित स्थान है: एक फ़ाइल, कोई सर्वर प्रक्रिया नहीं, और पूरा इतिहास आपके द्वारा पहले से लिए जा रहे बैकअप में सुरक्षित रहता है। विस्तृत रन डेटा के लिए Hurl के --report-json आउटपुट को पार्स करें; JSON और JUnit XML दोनों ही मशीन द्वारा पढ़े जाने योग्य प्रारूप हैं।
कंटेनर रीबिल्ड के बाद क्या सुरक्षित रहना चाहिए
मॉक डेफिनिशन और टेस्ट सुइट्स सोर्स कोड होते हैं। इन्हें उस सर्विस के साथ रिपॉजिटरी में होना चाहिए जिसका ये वर्णन करते हैं, और इन्हें उसी पुल रिक्वेस्ट में बदला जाना चाहिए जिसमें एंडपॉइंट बदला गया है। वेब UI में एडिट किया गया स्टब, या रनटाइम पर REST API के माध्यम से MockServer पर पुश की गई एक्सपेक्टेशन को रीबिल्ड के बाद सुरक्षित रखने के लिए एक्सपोर्ट या परसिस्टेंस सेटअप की आवश्यकता होती है। docker compose down रन करने पर कंटेनर की मेमोरी और राइटेबल लेयर्स नष्ट हो जाती हैं; बाइंड माउंट्स या नेम्ड वॉल्यूम्स में स्टोर किया गया डेटा सुरक्षित रहता है। यदि आपकी रिपॉजिटरी आपके अपने हार्डवेयर पर भी चलती है, तो एक सेल्फ-होस्टेड git सर्वर फिक्स्चर और सर्विस को एक ही ट्रस्ट बाउंड्री के भीतर रखता है।
अब व्यावहारिक नियम। इमेज टैग्स को पिन करें, क्योंकि latest आपकी रिपॉजिटरी में बिना किसी बदलाव के यह बदल सकता है कि आपका मॉक रिक्वेस्ट से कैसे मैच करता है, और उस विफलता के कारण का पता लगाना बहुत कठिन होता है। स्टब डायरेक्टरीज को रीड-ओनली माउंट करें जब टूल को उनमें लिखने की आवश्यकता न हो। मॉक के स्टब्स को कभी भी नेम्ड Docker वॉल्यूम में न रखें, क्योंकि तब वॉल्यूम ही 'सोर्स ऑफ ट्रुथ' बन जाता है और git में मौजूद कॉपी चुपचाप गलत हो जाती है।
एक और बात, जो अक्सर लोगों को फंसाती है। यदि आप प्रॉक्सी के माध्यम से वास्तविक ट्रैफिक रिकॉर्ड करके स्टब्स बनाते हैं, तो कमिट करने से पहले हर जनरेट की गई फाइल को पढ़ें। रिकॉर्डिंग में वही डेटा होता है जो अपस्ट्रीम ने वापस भेजा है, जिसमें बेयरर टोकन्स और ग्राहकों के ईमेल पते शामिल हो सकते हैं। इसे कमिट करने से यह आपकी रिपॉजिटरी में स्थायी रूप से दर्ज हो जाता है, क्योंकि git डिलीट किए गए कंटेंट को हिस्ट्री में बनाए रखता है।
FAQ
API mock server और API test runner में क्या अंतर है?
एक mock server requests का उत्तर देता है। यह एक ऐसी dependency की जगह लेता है जिसे आप CI से call नहीं कर सकते; कुछ tools contract tests भी चलाते हैं और उनके परिणाम रिपोर्ट करते हैं। एक API test runner आपकी अपनी service को requests भेजता है, responses पर assertions लागू करता है, एक call से values को अगली call में ले जाता है, और assertion विफल होने पर non-zero exit code देता है। ये अलग-अलग समस्याओं का समाधान करते हैं, और एक सामान्य setup में दोनों एक साथ चलते हैं: runner आपकी service को call करता है जबकि आपकी service mock को call करती है।
क्या मैं किसी hosted CI runner से internal API को test कर सकता हूँ?
हाँ, private networking के साथ। GitHub-hosted runners, API को public किए बिना private resources तक पहुँचने के लिए WireGuard overlay या Azure Virtual Network का समर्थन करते हैं। API को publish करना, tunnel चलाना, या public staging copy बनाए रखना अन्य विकल्प हैं, और प्रत्येक एक ऐसी प्रणाली जोड़ता है जो विफल हो सकती है या data leak कर सकती है। उसी private network पर स्थित एक runner सीधे service को call करता है, जो कि इस काम को self-host करने का मुख्य व्यावहारिक कारण है।
Mock stubs और API test suites कहाँ होने चाहिए?
Git में, उस service के साथ जिसका वे वर्णन करते हैं। जो tools definitions को files के रूप में store करते हैं, जैसे WireMock की mappings/ directory, Mockoon की data file, Hurl files और Bruno का .bru folder, वे आपको code review और container rebuild की सुविधा देते हैं जिसमें कोई अतिरिक्त लागत नहीं आती। जो tools definitions को database या web UI में store करते हैं, उन्हें backup plan और export step की आवश्यकता होती है, और export वह हिस्सा है जिसे लोग तब तक भूल जाते हैं जब तक container नष्ट न हो जाए।
यदि stub सही दिखता है तो मेरा mock 404 क्यों लौटाता है?
WireMock केवल तभी stub serve करता है जब request उसके configured matchers को संतुष्ट करती है। एक unmatched request को 404 मिलता है; जब कोई near match मौजूद होता है, तो body Request was not matched से शुरू होती है, जिसके बाद निकटतम stub के साथ एक diff होता है, और वह diff उस field का नाम बताता है जो भिन्न है। यदि कोई stub mappings न हों, तो body इसके बजाय यह बताती है कि instance में कोई mapping नहीं है। इसके सामान्य कारणों में path के अंत में trailing slash, एक Content-Type header जिसकी stub को आवश्यकता है लेकिन आपके client ने नहीं भेजा, variable segment के लिए stub को urlPathPattern की आवश्यकता होने पर urlPath का उपयोग, और body matcher का payload के साथ मेल न खाना शामिल है। यह पुष्टि करने के लिए कि request mock तक पहुँची भी है या नहीं, सबसे पहले /__admin/requests की जाँच करें।
यदि मेरे पास staging environment है, तो क्या मुझे अभी भी mocks की आवश्यकता है?
हाँ, दो कारणों से। एक upstream की staging copy जिसे आप नियंत्रित नहीं करते, वह भी down हो सकती है और आप पर rate limit लगा सकती है, जिससे आपकी suite उन कारणों से विफल हो जाती है जिनका आपके code से कोई लेना-देना नहीं है। यह उन responses को भी उत्पन्न नहीं कर सकती जिनकी आपको test करने के लिए सबसे अधिक आवश्यकता होती है, जैसे कि declined card या gateway timeout। एक mock उन्हें मांग पर local network की गति से लौटाता है, जो sandbox के मुकाबले मिनटों में चलने वाली suite को सेकंडों में पूरा कर देता है। Release से पहले अंतिम जाँच के लिए staging रखें और CI में mocks का उपयोग करें।