SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor · Güncellendi 2026-10-30

VPS üzerinde API mock ve test süreçleri nasıl kurulur?

API mock sunucuları ve test çalıştırıcılarını kendi VPS altyapınızda nasıl yöneteceğinizi öğrenin. WireMock ve Hurl kullanarak CI süreçlerinizi optimize edin.

Tek bir depoyu paylaşan iki görev

Self-hosted API mock oluşturma ve test etme birbirinden farklı iki görevdir; bunları tek bir iş gibi ele almak bir haftalık zaman kaybına yol açar. Bir mock sunucusu, CI ortamından çağrılamayan bir bağımlılığın yerine geçer: bir ödeme sağlayıcısı, bir iş ortağı API'si, hız sınırlamasına (rate limit) tabi bir upstream veya başka bir ekibin henüz yayınlamadığı bir servis. Bir API test çalıştırıcısı (test runner), kendi uç noktalarınızı belirli bir sırada çağırır ve yanıtları doğrular; bir yanıttan aldığı değerleri bir sonraki isteğe taşır.

Bazı araçlar her iki görevi de yerine getirir. Bir mock sunucusunun temel görevi isteklere yanıt vermektir. Bir test çalıştırıcısının ise bir kart reddedildiğinde ödeme sağlayıcısının ne döndüreceği konusunda bir görüşü yoktur. Hali hazırda bir sunucu kiralayan çoğu ekip, sonunda her ikisinden birer tane çalıştırır; bunlar aynı Docker Compose dosyası ile başlatılır ve aynı pull request içerisinde gözden geçirilir.

Neden API mock ve test işlemlerini kendi sunucunuzda barındırmalısınız?

Test verileriniz (fixtures), üretim ortamındaki verilerle aynı yapıdadır. Bir API testindeki istek gövdesi, ismi değiştirilmiş gerçek bir müşteri kaydıdır; bazen de kimse kontrol etmediği için isim olduğu gibi kalır. Kaydedilmiş stub dosyaları daha risklidir: proxy kaydı, yukarı akışın (upstream) döndürdüğü her şeyi depolar. Bu nedenle, kayıt yoluyla oluşturulan bir stub dizini, her dosya tek tek incelenene kadar canlı token'lar ve müşteri e-posta adresleri barındırır. Başkası tarafından barındırılan bir serviste bu veriler, başkasının güvenlik olayı ve sizin veri ifşanız haline gelir.

İkinci neden erişilebilirliktir. Özel bir adrese bağlı bir servis, barındırılan bir çalıştırıcının (runner) ona ulaşabilmesi için özel bir ağ bağlantısına ihtiyaç duyar. Her geçici çözümün bir maliyeti vardır. API'yi test etmek amacıyla internete açmak, onun özel kalma amacını ortadan kaldırır. Bir tünel veya herkese açık bir hazırlık (staging) kopyası, bakımı gereken ek bir sistemdir; ayrıca hazırlık kopyası, sürümler arasında üretim ortamından uzaklaşır. GitHub tarafından barındırılan çalıştırıcılar, WireGuard katmanı veya Azure Virtual Network üzerinden özel erişimi destekler. Aynı özel ağ üzerindeki bir çalıştırıcı ise servisi doğrudan çağırır ve bunların hiçbirine ihtiyaç duymaz; bu da kendi sunucunuzda barındırılan bir GitHub Actions çalıştırıcısı kullanmanın arkasındaki pratik argümandır.

Hangi self-hosted mock sunucusunu çalıştırmalısınız?

Bunların her biri, sahibi olduğunuz bir sunucuda container olarak çalışır. Önemli olan soru, her birinin neyi doğruluk kaynağı (source of truth) olarak kabul ettiğidir; çünkü bu, container'ı yeniden oluşturmanın size hiçbir maliyetinin mi olacağını yoksa bir öğleden sonranıza mı mal olacağını belirler.

  • WireMock, her stub'ı mappings/ dizininde bir JSON dosyası olarak tutar; büyük yanıt gövdeleri ise __files/ içindedir. İmaj wiremock/wiremock'dır, container içindeki kök dizini /home/wiremock'dir ve aynı zamanda kayıt yapan bir proxy olarak çalışır. Dosyaların diskte olması, mock'un diğer kodlar gibi git içinde yaşaması anlamına gelir.
  • Mockoon CLI, tüm bir mock API'yi tek bir JSON veri dosyasında tutar. npm install -g @mockoon/cli ile kurun ve mockoon-cli start --data ./data-file.json ile başlatın ya da ilgili dosyayı bind mount ederek mockoon/cli imajını çalıştırın. Masaüstü uygulaması aynı dosyayı düzenlediği için, arayüzde tasarım yapmak ve sonucu commit etmek uyumlu kalır.
  • MockServer, mockserver/mockserver imajından çalışır ve 1080 numaralı portu dinler. Beklentiler (expectations) kendi REST API'si üzerinden gelir; bu durum test kodları için kullanışlı, dağıtım için ise risklidir: varsayılan olarak, bir HTTP çağrısı ile oluşturulan beklenti container yeniden başlatıldığında kaybolur. Kalıcı olması gereken stub'lar için JSON başlatma dosyasını kullanın. Çalışma zamanındaki değişiklikleri korumak için persistExpectations özelliğini etkinleştirin, çıktı dosyasını container dışında kalıcı hale getirin ve başlangıçta initializationJsonPath üzerinden yükleyin.
  • Prism, mock'u ayrı stub dosyaları yerine OpenAPI belgenizden oluşturur. npm install -g @stoplight/prism-cli ile kurun, ardından prism mock openapi.yaml komutunu çalıştırın. Container içinde -h 0.0.0.0 ekleyin; çünkü Prism varsayılan olarak localhost'a bağlanır ve aksi takdirde container dışından erişilemez.
  • Microcks, kapsamlı seçenektir: OpenAPI belgelerini ve Postman koleksiyonlarını içe aktaran, bunları mock olarak sunan ve sözleşme testlerini (contract tests) çalıştıran bir web arayüzüdür. Tam kurulum için MongoDB ve Keycloak, ayrıca asenkron özellikleri için Kafka gerekir. Hepsi bir arada olan microcks-uber imajı, projenin geçici kullanım için uygun olduğunu belirttiği bellek içi (in-memory) bir MongoDB içerir; bu nedenle arayüzde oluşturulan her şeyi atılabilir olarak görün ve kaynak dosyaları git içinde tutun.

Hangi self-hosted API test aracı kullanılmalı?

Buradaki görev bir dizidir: kimlik doğrula, sipariş oluştur, geri oku, durumun değiştiğini doğrula. Bu, bir yanıttan alınan değerin bir sonraki istekte kullanılmasını gerektirir. Çağrılar arasında durum (state) taşıyamayan bir araç, API test aracı değil, yalnızca bir sağlık kontrolü aracıdır.

  • Hurl, tek bir binary dosya üzerinden düz metin formatındaki HTTP isteklerini çalıştırır. Bir [Captures] bölümü yanıttan değerleri çeker, bir [Asserts] bölümü bunları kontrol eder ve --test bunu özet raporu ve çıkış kodu olan bir test çalıştırıcısına dönüştürür. Ağustos 2026 itibarıyla güncel sürüm 8.0.1'dir.
  • Bruno CLI, bir klasör dolusu .bru dosyasını çalıştırır. npm install -g @usebruno/cli ile kurun ve ardından bru run folder --env Local --reporter-junit results.xml ile çalıştırın. Koleksiyon formatı tasarım gereği dizin içindeki metin dosyalarından oluştuğu için, değişiklikler (diff) kod incelemelerinde okunabilir durumdadır.
  • Newman, Postman koleksiyonlarını Postman dışında çalıştırır: npm install -g newman, ardından newman run collection.json -r cli,junit --reporter-junit-export results.xml. Buradaki sorun formattır. Newman, dışa aktarılan koleksiyonları v2.1 JSON formatında çalıştırır. Postman artık v3 koleksiyon formatını ve Postman CLI aracılığıyla Native Git iş akışlarını desteklemektedir. Postman belgeleri, Newman'ın artık güncelleme veya düzeltme almayacağını belirtmekte ve betikler ile CI hatlarının Postman CLI'ya taşınmasını önermektedir.
  • Schemathesis farklı bir kontrol türüdür. Bir OpenAPI şemasını okur ve şemanızın imkansız olduğunu belirttiği yanıtları üretmeye çalışan test senaryoları oluşturur: uvx schemathesis run https://your.api/openapi.json. Çökmeleri ve sözleşme ihlallerini bulur; ancak iş kurallarınız hakkında hiçbir bilgisi yoktur, bu nedenle betik tabanlı bir test paketinin yerini almak yerine onun yanında çalışır.
  • Hoppscotch self-hosted, web arayüzü seçeneğidir ve bir Postgres örneği gerektirir. Kurulumdan önce bu ödünleşimi (tradeoff) göz önünde bulundurun: koleksiyonlar deponuzda değil, bir veritabanında yaşar.

Kaçınılması gereken bir araç: Step CI hala araç listelerinde görünmekte ve YAML iş akışı formatı kolay okunmaktadır, ancak depo en son Ağustos 2024'te commit almıştır. CI süreciniz ile API'niz arasında yer alan bir program, bakımı yapılmayan kodlar için uygun bir yer değildir.

Mock sunucusunu güvenlik duvarının arkasına alın

Aşağıdaki kurulum, bir ödeme sağlayıcısı yerine geçmesi için WireMock kullanır. Compose dosyası formatı sizin için yeniyse, VPS üzerinde Docker Compose bölümü, bu kısmın varsaydığı yaşam döngüsü komutlarını açıklar.

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

Port üzerindeki 127.0.0.1: ön eki, işin önemli kısmıdır. Yalın bir 8080:8080, mock servisini genel IP adresiniz dahil tüm arayüzlerde yayınlar ve ufw o portu reddetse bile servis erişilebilir kalır; çünkü Docker, yayınlanan trafiği ufw'nin INPUT kurallarına ulaşmadan önce nat tablosu üzerinden yönlendirir. Yayınlanan portun yalnızca ana makineden erişilebilir kalmasını sağlamak için, Engine 28.0.0 veya sonraki sürümlerde Docker'ın varsayılan köprü ağını kullanarak loopback adresine bağlayın. Daha eski sürümler, aynı katman 2 ağındaki ana makinelerin localhost'a yayınlanan portlara erişmesine izin verir. Özel bir arayüz adresine bağlamak, o adrese yönlendirme yapabilen ağlardan erişime hala izin verir.

Test edilen servisiniz daha sonra mock servisini işaret eder. Servis aynı compose projesi içinde çalıştığında, mock servisinin temel URL'si http://mock-payments:8080 olur; çünkü compose, servis isimlerini kendi ağı üzerinde çözer. Servis ana makinede çalıştığında ise bu adres http://127.0.0.1:8080 olur. Bunu kod içinde değil, her zaman bir ortam değişkeni (environment variable) aracılığıyla ayarlayın; aksi takdirde test URL'si üretim ortamına taşınır.

Stub dosyaları, her biri bir JSON dosyası olacak şekilde ./mocks/payments/mappings/ dizinine yerleştirilir.

{
  "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 }
  }
}

Servisi başlatın ve ardından nelerin yüklendiğini kontrol edin.

docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings

--wait, container sağlıklı olduğunu bildirene kadar bekler; bu, WireMock imajının /__admin/health uç noktasına karşı bir HEALTHCHECK içermesi sayesinde çalışır. mappings çağrısı, sunucunun okuduğu her stub'ı listeler. Yazdığınız bir stub bu listede yoksa, hiç yüklenmemiş demektir: dosyanın mount edilen kök dizin yerine mappings/ altında durup durmadığını ve JSON formatının doğruluğunu kontrol edin.

Bir istek geldiğinde ve hiçbir stub eşleşmediğinde, WireMock 404 yanıtını verir. Yakın bir eşleşme bulursa, gövde kısmı Request was not matched ile başlar ve ardından en yakın stub ile olan farkı gösterir. Hiçbir stub eşlemesi yoksa, gövde No response could be served as there are no stub mappings in this WireMock instance. şeklindedir. Bir değişiklik yapmadan önce farkı okuyun, çünkü fark raporu tam olarak hangi alanın farklı olduğunu belirtir. Bu genellikle stub içinde /v1/charges yazan bir yerin /v1/charge yoluna sahip olması durumudur.

Testi, çağrılar arasında durumun taşındığı bir dizi olarak yazın

Hurl dosyaları düz metin dosyalarıdır. Projenin releases sayfasından .deb paketini yükleyin.

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

Kendi API'nizi mock üzerinde çalıştıran bir test paketi tests/checkout.hurl dizininde bulunur.

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] bloğu, bunu iki alakasız istek yerine bir API testi yapan kısımdır. order_id, ilk yanıttan okunur ve ikinci isteğin URL'sine yerleştirilir. charge_id üzerindeki doğrulama, tüm bu sürecin temel amacıdır: servisin ödeme sağlayıcısını çağırdığını ve dönen yanıtı kaydettiğini kanıtlar; karşılaştırılan değer ise WireMock stub dosyasına yazdığınız değerdir. Artık tek bir dosya, akışın her iki yarısını da kapsamaktadır.

hurl --test --variable base_url=http://127.0.0.1:3000 \
  --report-junit reports/junit.xml \
  --report-json reports/json \
  tests/

Başarılı bir çalıştırma, her dosya için bir satır ve bir özet çıktısı verir.

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

Başarısızlık durumunda error: Assert failure ile dosya ve satır numarası yazdırılır, ardından elde edilen değer ile beklenen değer karşılaştırılır ve hurl sıfır olmayan bir çıkış kodu döndürerek CI sürecini durdurur. Eğer status, paid beklediğiniz yerde pending değerini okuyorsa, servisiniz mock yanıtını işlememiştir. Bir sonraki adım, çağrının mock'a ulaşıp ulaşmadığını gösteren /__admin/requests adresindeki WireMock istek günlüğünü incelemektir.

Test paketini kendi CI runner'ınız üzerinden tetikleyin

Aynı sunucu üzerinde kayıtlı bir runner ile iş akışı oldukça kısadır. Runner, ana makine üzerinde çalışan basit bir süreçtir; bu nedenle docker ve hurl araçlarının o makinede yüklü olması gerekir. Barındırılan (hosted) bir imajdan hiçbir ayar devralınmaz.

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 down

Arşivleme adımındaki if: always() parametresi önemlidir. Bu parametre kullanılmazsa, başarısız olan bir test çalışması kopyalama işlemini atlar ve incelemek istediğiniz raporu kaybedersiniz. Kopyalama işleminin çalışma alanı (workspace) dışında bir yere yapılması gerekir; çünkü actions/checkout@v4 varsayılan olarak bir sonraki checkout işleminden önce git clean -ffdx komutunu çalıştırır. Bu durum, takip edilmeyen raporların depo dizininden silinmesine neden olur.

Sadece son çalıştırmayı değil, sonuçların tamamını saklayın

Commit başına bir JUnit XML dosyası tek bir soruya yanıt verir: test başarılı mı? Bu dosyalar açılmadığı sürece, bir uç noktanın ne zaman yavaşlamaya başladığına dair bilgi vermezler. Eğilimleri takip etmek için, her çalıştırmada elde edilen verileri aynı sunucudaki küçük bir veritabanına bir satır olarak ekleyin. Commit SHA değerini, dosya adını, başarılı test sayısını, başarısız test sayısını ve süreyi tutan tek bir tablo yeterlidir. VPS üzerinde SQLite kullanımı, bu işlem için makul bir yöntemdir: tek bir dosya, sunucu süreci gerektirmez ve tüm geçmiş, halihazırda aldığınız yedeklerin içinde yer alır. Ayrıntılı çalıştırma verileri için Hurl'ün --report-json çıktısını ayrıştırın; hem JSON hem de JUnit XML formatları makine tarafından okunabilir yapıdadır.

Container yeniden oluşturma sürecinde nelerin korunması gerekir

Mock tanımları ve test paketleri kaynak kodun bir parçasıdır. Bu dosyalar, tanımladıkları servisin yanında bir depoda tutulmalı ve uç noktayı değiştiren pull request ile birlikte güncellenmelidir. Web arayüzü üzerinden düzenlenen bir stub veya çalışma zamanında REST API aracılığıyla MockServer'a gönderilen bir beklenti, yeniden oluşturma sürecinde varlığını korumak için bir dışa aktarma veya kalıcılık yapılandırmasına ihtiyaç duyar. docker compose down komutunu çalıştırdığınızda container belleği ve yazılabilir katmanlar silinir; bind mount veya named volume üzerinde saklanan veriler ise korunur. Depolarınız kendi donanımınız üzerinde çalışıyorsa, kendi barındırdığınız bir git sunucusu, fixture dosyalarını ve servisi tek bir güven sınırında tutmanızı sağlar.

Uygulamaya yönelik kurallar ise şöyledir: Image etiketlerini sabitleyin; çünkü latest, deponuzda hiçbir değişiklik yapmasanız bile mock'un istekleri eşleştirme biçimini değiştirebilir ve bu hatanın kaynağını tespit etmek oldukça zordur. Araç yazma erişimine ihtiyaç duymadığında, stub dizinlerini salt okunur (read-only) olarak mount edin. Bir mock'un stub dosyalarını asla named Docker volume içine koymayın; aksi takdirde volume gerçek veri kaynağı haline gelir ve git içindeki kopya sessizce geçersiz kalır.

Bir kural daha var ki, birçok kullanıcıyı zor durumda bırakır. Eğer stub dosyalarını bir proxy üzerinden gerçek trafiği kaydederek oluşturuyorsanız, commit etmeden önce üretilen her dosyayı inceleyin. Bir kayıt, upstream tarafından gönderilen bearer token'lar ve müşteri e-posta adresleri dahil olmak üzere her şeyi olduğu gibi içerir. Bu dosyayı commit etmek, içeriği deponuza kalıcı olarak ekler; çünkü git, silinen içerikleri geçmişinde tutmaya devam eder.

FAQ

API mock sunucusu ile API test çalıştırıcısı arasındaki fark nedir?

Bir mock sunucusu isteklere yanıt verir. CI sürecinde çağrılamayan bir bağımlılığın yerini tutar; bazı araçlar ayrıca sözleşme (contract) testlerini çalıştırır ve sonuçlarını raporlar. Bir API test çalıştırıcısı ise kendi servisinize istekler gönderir, yanıtları doğrular, bir çağrıdan aldığı değerleri bir sonrakine aktarır ve bir doğrulama başarısız olduğunda sıfırdan farklı bir çıkış kodu döndürür. Bu araçlar farklı sorunları çözer ve tipik bir kurulumda her ikisi de aynı anda çalışır: test çalıştırıcısı sizin servisinizi çağırırken, servisiniz de mock sunucusunu çağırır.

Barındırılan bir CI çalıştırıcısından dahili bir API'yi test edebilir miyim?

Evet, özel ağ (private networking) ile mümkündür. GitHub tarafından barındırılan çalıştırıcılar, API'yi dış dünyaya açmadan özel kaynaklara ulaşmak için WireGuard katmanını veya Azure Virtual Network yapısını destekler. API'yi yayınlamak, bir tünel çalıştırmak veya herkese açık bir staging kopyası tutmak diğer seçeneklerdir; ancak bunların her biri hata yapabilecek veya veri sızdırabilecek yeni bir sistem ekler. Aynı özel ağ üzerindeki bir çalıştırıcı servisi doğrudan çağırır; ekiplerin bu işi kendi sunucularında barındırmasının temel pratik nedeni budur.

Mock taslakları ve API test paketleri nerede tutulmalıdır?

Git üzerinde, tanımladıkları servisin yanında tutulmalıdır. Tanımları dosya olarak saklayan WireMock'un mappings/ dizini, Mockoon'un veri dosyası, Hurl dosyaları ve Bruno'nun .bru klasörü gibi araçlar, kod incelemesi yapmanıza ve maliyetsiz bir şekilde container yeniden oluşturmanıza olanak tanır. Tanımları veritabanında veya web arayüzünde saklayan araçlar ise bir yedekleme planına ve dışa aktarma adımına ihtiyaç duyar; dışa aktarma işlemi ise genellikle container silinene kadar unutulan kısımdır.

Taslak doğru görünmesine rağmen mock neden 404 hatası döndürüyor?

WireMock, bir taslağı yalnızca istek yapılandırılmış eşleştiricileri karşıladığında sunar. Eşleşmeyen bir istek 404 sonucunu alır; yakın bir eşleşme mevcut olduğunda yanıt gövdesi Request was not matched ile başlar ve ardından en yakın taslak ile aradaki farkı gösterir; bu fark, uyuşmayan alanı belirtir. Hiçbir taslak eşlemesi yoksa, yanıt gövdesi örnekte hiç taslak bulunmadığını açıklar. Yaygın nedenler arasında yoldaki (path) sondaki eğik çizgi, taslağın gerektirdiği ancak istemcinizin göndermediği bir Content-Type başlığı, değişken bir segment için taslağın urlPathPattern gerektirdiği yerde urlPath kullanılması ve yük (payload) ile uyuşmayan bir gövde eşleştiricisi yer alır. İsteğin mock sunucusuna ulaştığını doğrulamak için önce /__admin/requests kısmını kontrol edin.

Staging ortamım varsa yine de mock kullanmalı mıyım?

Evet, iki nedenden dolayı. Kontrolünüz altında olmayan bir yukarı akışın (upstream) staging kopyası da kesintiye uğrayabilir veya hız sınırlaması (rate limit) uygulayabilir; bu durumda test paketiniz kodunuzla ilgisi olmayan nedenlerle başarısız olur. Ayrıca staging ortamı, reddedilen bir kart veya ağ geçidi zaman aşımı (gateway timeout) gibi test etmeniz gereken yanıtları her zaman üretemez. Bir mock sunucusu bunları yerel ağ hızında talep üzerine döndürür; bu da sandbox ortamında dakikalar süren bir test paketini saniyeler süren bir işleme dönüştürür. Staging ortamını sürüm öncesi son kontrol için saklayın, CI sürecinde ise mock kullanın.

Bu yazı işinize yaradı mı?