PHP ile Pact Kullanarak Harici API’lerde Sözleşme Testi (Gerçek Laravel Örneği)

<p>Bunu zor yoldan öğrendim.</p>

<p>Bir projede, tüm testlerim başarılıydı. Mock'larım tam olarak beklediğim gibi geri döndü. Bir hafta sonra, dış API, yanıtın bir alanını kaldırdı. Mock'larım bu değişikliği bilmiyordu. Üretim ise biliyordu.</p>

<p>Mock'lar her şeyin yolunda olduğunu söyledi. Gerçekler ise karşıtını gösterdi.</p>

<p>İşte bu tür bir sorun <strong>contract testing</strong>'in çözmeyi amaçladığı tam yer. Bu makalede, gerçek dünyadaki bir *<em>Laravel</em>* örneği ile PHP'de dış API'ler için contract testing nasıl kullanılır, göstereceğim.</p>

<h2>
    <a name="why-mocking-external-apis-is-not-enough" href="#why-mocking-external-apis-is-not-enough">
    </a>
    Neden Dış API'leri Mocklamak Yeterli Değil
</h2>

<p>Dış API'leri mocklamak faydalıdır. Hâlâ yapıyorum. Testleri hızlı, belirleyici ve ucuz hale getirir. Ancak mock'ların bir ölümcül hatası vardır:</p>

<blockquote>
    <p>API hakkında varsayımlarınızı test ederler, API'yi değil.</p>
</blockquote>

<p>Üretimde gördüğüm tipik problemler:</p>

<ul>
    <li>API bir alanı kaldırır veya adını değiştirir.</li>
    <li>İç içe olan yapının şekli değişir.</li>
    <li>API bazı uç durumlarda 200 yerine 404 döndürmeye başlar.</li>
    <li>API, istek gövdesine bir zorunlu alan ekler.</li>
</ul>

<p>Mock'larınızı manuel olarak güncellemedikçe bunları asla yakalayamazsınız. Bu, mock'ların sessizce gerçeklikten uzaklaşabileceği anlamına gelir.</p>

<h2>
    <a name="what-is-contract-testing-in-plain-english" href="#what-is-contract-testing-in-plain-english">
    </a>
    Contract Testing Nedir (Açık Bir Dille)
</h2>

<p>Contract testing, mocking ve tam entegrasyon testleri arasında yer alır.</p>

<p>Şunu söylemek yerine:</p>

<blockquote>
    <p>“API'nin döndüğünü düşündüğüm şey bu,”</p>
</blockquote>

<p;>şunu söylersiniz:</p>

<blockquote>
    <p>“Uygulamam (tüketici) ile API (sağlayıcı) arasındaki sözleşme budur.”</p>
</blockquote>

<p>Tüketici odaklı contract testing ile:</p>

<p>Sağlayıcı, sözleşmeyi bozan bir değişiklik yaparsa, testler <strong>üretim bozulmadan önce</strong> başarısız olur.</p>

<p>Bu, bozulma yapan API değişikliklerini bir çalışma zamanı sürprizinden, bir inşa (build) zamanı hatasına dönüştürür.</p>

<h2>
    <a name="realworld-scenario-laravel-as-api-consumer" href="#realworld-scenario-laravel-as-api-consumer">
    </a>
    Gerçek Dünya Senaryosu: Laravel'in API Tüketicisi Olarak Kullanımı
</h2>

<p>Bir Laravel uygulamasının harici bir faturalama API'si ile entegre olduğunu varsayalım:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>GET /api/customers/{id}

<p>Laravel servisin:</p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>class BillingClient

    return $response->json();
}

<p>Uygulamanız şuna bağlıdır:</p>

<p>Eğer sağlayıcı <em>is_active</em> alanını kaldırırsa, uygulamanız bozulur. Mock'lar bunu yakalayamaz. Contract testing yakalayacaktır.</p>

<h2>
    <a name="stepbystep-contract-testing-with-pact-in-laravel" href="#stepbystep-contract-testing-with-pact-in-laravel">
    </a>
    Adım Adım: Laravel'de Pact ile Contract Testing
</h2>

<p><strong>Pact'ın PHP için Kurulumu</strong></p>

<p>Test ortamınız için Pact bağımlılıklarını yükleyin:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>composer require --dev pact-foundation/pact-php

<p>Pact CLI'sının yerel olarak veya CI'de çalışır durumda olması gerekir (genellikle Docker aracılığıyla).</p>

<h2>
    <a name="writing-the-consumer-contract-test" href="#writing-the-consumer-contract-test">
    </a>
    Tüketici Sözleşme Testi Yazma
</h2>

<p>Hedef: Laravel uygulamanızın API'den <strong>beklediğini</strong> tanımlamak.</p>

<p>Örnek tüketici testi:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>public function test_it_fetches_customer_from_billing_api()

$builder
    ->given('Customer 123 exists')
    ->uponReceiving('A request for customer 123')
    ->with([
        'method' => 'GET',
        'path'   => '/api/customers/123',
    ])
    ->willRespondWith([
        'status' => 200,
        'headers' => ['Content-Type' => 'application/json'],
        'body' => [
            'id' => 123,
            'email' => '[email protected]',
            'is_active' => true,
        ],
    ]);

$builder->verify(function () {
    $client = new BillingClient();
    $customer = $client->getCustomer(123);

    $this->assertSame('[email protected]', $customer['email']);
    $this->assertTrue($customer['is_active']);
});

<p>Bu test:</p>

<ul>
    <li>beklenen isteği tanımlar</li>
    <li>beklenen yanıtı tanımlar</li>
    <li>bir <strong>sözleşme dosyası</strong> (Pact dosyası) üretir</li>
</ul>

<p>Bu sözleşme, tüketici ile sağlayıcı arasındaki <strong>tek gerçek kaynaktır</strong>.</p>

<h2>
    <a name="verifying-the-contract-on-the-provider-side" href="#verifying-the-contract-on-the-provider-side">
    </a>
    Sağlayıcı Tarafında Sözleşmeyi Doğrulama
</h2>

<p>Sağlayıcı tarafında, API ekibi Pact doğrulamasını çalıştırır:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>pact-verifier --provider-base-url=http://localhost:8000 \

<p>Eğer API artık is_active döndürmüyorsa, doğrulama başarısız olur.</p>

<p>Bu, mock'lardan anahtar bir farktır:</p>

<ul>
    <li>mock'lar yalnızca tüketiciyi test eder</li>
    <li>contract testing, anlaşmayı test eder</li>
</ul>

<h2>
    <a name="running-contract-tests-in-ci" href="#running-contract-tests-in-ci">
    </a>
    CI'de Sözleşme Testlerini Çalıştırma
</h2>

<p>Contract testing'in güçlü hale geldiği yer burasıdır.</p>

<p>Tipik CI akışı:</p>

<ol>
    <li>Tüketici testleri Pact sözleşmeleri oluşturur.</li>
    <li>Sağlayıcı pipeline sözleşmeleri doğrular.</li>
    <li>Pipeline, sözleşmeler bozulduğunda başarısız olur.</li>
</ol>

<p>Bu bir güvenlik ağı oluşturur:</p>

<blockquote>
    <p>API değişiklikleri mevcut tüketicileri bozuyorsa dağıtılamaz.</p>
</blockquote>

<h2>
    <a name="common-mistakes-with-contract-testing" href="#common-mistakes-with-contract-testing">
    </a>
    Contract Testing ile İlgili Yaygın Hatalar
</h2>

<p><strong>Yanıtları Aşırı Belirleme</strong></p>

<p>Her alanı kısıtlamayın eğer gerek yoksa.<br/>Sadece uygulamanızın gerçekten kullandığını tanımlayın.</p>

<p><strong>Yalnızca Mutlu Yolları Test Etmek</strong></p>

<p>Hata sözleşmelerini de ekleyin:</p>

<ul>
    <li>404 yanıtları</li>
    <li>doğrulama hataları</li>
    <li>yetkisiz yanıtlar</li>
</ul>

<p><strong>Sözleşmeleri Sürümlememek</strong></p>

<p>Sözleşmeleri kod gibi yönetin. Sürümleyin.</p>

<p><strong>CI'de Sözleşmeleri Zorlamamak</strong></p>

<p>Eğer hiçbiri pipeline'lar tarafından zorlanmıyorsa, contract testing sadece bir dokümandır.</p>

<h2>
    <a name="when-contract-testing-is-worth-it-and-when-its-overkill" href="#when-contract-testing-is-worth-it-and-when-its-overkill">
    </a>
    Contract Testing Ne Zaman Değerlidir (ve Ne Zaman Aşırı)
</h2>

<p><strong>Contract testing değerlidir:</strong></p>

<ul>
    <li>bireysel ekiplerin farklı hizmetleri yönettiği durumlarda</li>
    <li>API'lerin sıklıkla geliştiği durumlarda</li>
    <li>bozulma yapan değişikliklerin maliyetli olduğu durumlarda</li>
</ul>

<p><strong>Muhtemelen aşırı gelebilir:</strong></p>

<ul>
    <li>entegrasyon önemsiz olduğunda</li>
    <li>sağlayıcıyı kontrol etmediğinizde</li>
    <li>API kararlı ve nadiren değiştiğinde</li>
</ul>

<p>Contract testing bir keskin alet, bir çekiç değil. API stabilitesinin önemli olduğu yerlerde kullanın.</p>

<h2>
    <a name="how-contract-testing-fits-into-your-laravel-testing-strategy" href="#how-contract-testing-fits-into-your-laravel-testing-strategy">
    </a>
    Contract Testing, Laravel Test Stratejinize Nasıl Uygun Düşer
</h2>

<p>Gerçek projelerde test katmanlarını nasıl düşündüğüm:</p>

<ul>
    <li>Unit testleri – iş mantığı</li>
    <li>Feature testleri – HTTP akışları</li>
    <li>Mock'lar – yavaş veya dengesiz hizmetleri izole edin</li>
    <li>Contract testleri – entegrasyonları bozulma yapan değişikliklere karşı koruyun</li>
</ul>

<p>Mock'lar testlerinizi hızlı tutulur.<br/>Contract testleri entegrasyonlarınızı dürüst tutar.</p>

<p>Farklı problemleri çözerler ve birlikte en iyi şekilde çalışırlar.</p>

<h2>
    <a name="final-thoughts" href="#final-thoughts">
    </a>
    Son Düşünceler
</h2>

<p>Dış API'leri mocklamak gereklidir — ama yeterli değildir.</p>

<p>Eğer uygulamanız harici hizmetlere bağımlıysa ve üretimde bozulma yapan bir API değişikliği ile hiç şaşırmadıysanız, contract testing kaybolan güvenlik ağını sağlıyor demektir.</p>

<p>Her şeyi contract-test yapmanıza gerek yok. Öncelikle bir kritik entegrasyonla başlayın. Bir sözleşme ekleyin. CI'nizi bunun uygulanmasını zorlayacak şekilde ayarlayın. İlk bozulma sonucu değişiklikleri dağıtımdan önce yakaladığı anda, contract testing kendini ödeyecektir.</p>