Software Engineer Encyclopedia
0%
Domain 05 · Security & Software Testing · Pillar

Contract Testing بـ Pact وBDD بـ Reqnroll: وربطهم بالـ CI

Contract Testing with Pact and BDD with Reqnroll

ليه الـ integration tests بين الخدمات بتتكسر وبتبطأ، وإزاي consumer-driven contracts (Pact) بتختبر التوافق من غير بيئة كاملة؛ الـ consumer tests، الـ provider verification، الـ provider states، الـ Pact Broker وcan-i-deploy؛ وBDD: Gherkin كلغة مشتركة مع الـ product، Reqnroll (خليفة SpecFlow) في .NET، وإمتى BDD بيضيف قيمة وإمتى بيبقى ceremony — وكلهم جوه pipeline.

  • Intermediate
  • ~7 min read
  • 13 sections
  • 6 code examples
  • 2 diagrams
  • 4 questions
  • Priority L2 · Essential
  • PactNet 5.x (Pact Specification v4) · Pact Broker / PactFlow · Reqnroll 2.x/3.x (SpecFlow successor) · xUnit · GitHub Actions — reviewed 2026-11-18

بعد الدرس ده هتقدر

  • تفرق بين schema checks (OpenAPI diff) وcontract tests وintegration/E2E tests
  • تكتب consumer test بـ PactNet بيولّد pact file من توقعات الـ client
  • تعمل provider verification على ASP.NET Core API مع provider states
  • تستخدم Pact Broker وcan-i-deploy عشان تمنع deploy بيكسر consumer
  • تكتب Gherkin scenarios كويسة وتنفذها بـ Reqnroll مع WebApplicationFactory
  • تصمم pipeline بيربط unit وcontract وBDD وE2E بتوقيت وتكلفة مناسبة

المتطلبات قبل ما تبدأ

01

المشكلة: الخدمتين شغالين لوحدهم ومكسورين مع بعض

Why integration between services breaks
Basics

فريق الـ billing غيّر اسم حقل في الـ response من planId لـ plan_id. كل الـ unit tests عندهم عدّت. الـ Angular والـ ingestion worker وقعوا في الإنتاج. الـ E2E tests كانت هتكتشف ده — لو كانت موجودة لكل التركيبات، وسريعة، ومستقرة. وده نادر. Contract testing بيملا الفجوة: كل consumer بيكتب «أنا بستخدم إيه بالظبط»، والـ provider بيتحقق إنه بيوفي بكل العقود دي قبل الـ deploy.

Consumer testAngular/worker vs Pact mockPact fileinteractions JSONPact Brokerversions + environmentsProvider verificationreal API + provider statescan-i-deploy?gate in each pipeline
Consumer tests produce a pact; the provider verifies it; the broker answers can-i-deploy
النوعبيكتشفما بيكتشفش
OpenAPI diffتغييرات schema بتكسر (حقل اتشال، type اتغير)هل الـ consumer فعلًا بيستخدم الحقل ده؟ وهل السلوك (status في حالة معينة) اتغير؟
Contract test (Pact)التوقعات الفعلية لكل consumer: request، response shape، status لحالات محددةمنطق البيزنس الكامل، الأداء
Integration testالخدمة مع dependencies حقيقية (DB)توافق مع خدمات تانية في نسخها الحالية
E2Eالـ flow الكاملبطيء وهش ومكلف — قليل منه بس
02

Consumer test بـ PactNet

Writing a consumer test
Practical

الـ consumer هنا: ingestion worker (‎.NET) بيكلم Billing API عشان يعرف حدود الخطة قبل ما يعالج مستند. الاختبار بيشغّل mock server من Pact، الكود الحقيقي بتاع الـ client بيكلمه، والـ interactions بتتسجل في pact file.

C#EntitlementsClientPactTests.cs (consumer side)
public sealed class EntitlementsClientPactTests
{
    private readonly IPactBuilderV4 _pact = Pact.V4("ingestion-worker", "billing-api", new PactConfig
    {
        PactDir = Path.Combine("..", "..", "..", "pacts")                 // pact JSON written here, then published to the broker
    }).WithHttpInteractions();

    [Fact]
    public async Task Gets_document_limit_for_an_active_tenant()
    {
        var tenantId = "6f1c2a10-0000-4000-8000-000000000001";
        _pact.UponReceiving("a request for tenant entitlements")
             .Given("tenant 6f1c… is on the Pro plan")                         // provider state
             .WithRequest(HttpMethod.Get, $"/api/tenants/{tenantId}/entitlements")
             .WithHeader("Accept", "application/json")
             .WillRespond()
             .WithStatus(HttpStatusCode.OK)
             .WithJsonBody(new
             {
                 plan = Match.Type("pro"),                                    // any string, not literally "pro"
                 limits = new { documents = Match.Integer(500), aiTokensPerMonth = Match.Integer(2_000_000) },
                 status = Match.Regex("active", "^(active|trialing|past_due)$")
             });

        await _pact.VerifyAsync(async ctx =>
        {
            var client = new EntitlementsClient(new HttpClient { BaseAddress = ctx.MockServerUri });  // the REAL client code
            var e = await client.GetAsync(Guid.Parse(tenantId), default);
            Assert.Equal(500, e.Limits.Documents);
        });
    }

    [Fact]
    public async Task Treats_404_as_unknown_tenant()
    {
        _pact.UponReceiving("a request for an unknown tenant")
             .Given("tenant does not exist")
             .WithRequest(HttpMethod.Get, "/api/tenants/00000000-0000-4000-8000-000000000000/entitlements")
             .WillRespond().WithStatus(HttpStatusCode.NotFound);

        await _pact.VerifyAsync(async ctx =>
        {
            var client = new EntitlementsClient(new HttpClient { BaseAddress = ctx.MockServerUri });
            await Assert.ThrowsAsync<UnknownTenantException>(() => client.GetAsync(Guid.Empty, default));
        });
    }
}
  • Matchers (Match.Type، Integer، Regex) بتخلي العقد عن الشكل مش القيم الحرفية — وإلا أي تغيير في بيانات الـ test عند الـ provider هيكسره.
  • اختبر اللي بتستخدمه بس: لو الـ worker ما بيقراش createdAt، ما تحطوش في العقد. كده الـ provider حر يغيّر أي حاجة محدش بيستخدمها — دي قيمة «consumer-driven».
  • حالات الأخطاء جزء من العقد (404، 402) — غالبًا هي اللي بتتكسر.
03

Provider verification على ASP.NET Core

Verifying the provider
Practical
C#BillingApiPactVerificationTests.cs (provider side)
public sealed class BillingApiPactVerificationTests(ITestOutputHelper output) : IClassFixture<BillingApiFixture>
{
    [Fact]
    public void Honours_all_consumer_pacts()
    {
        using var fixture = new BillingApiFixture();                       // starts the real API on a local port (Kestrel)
        var config = new PactVerifierConfig { Outputters = [new XunitOutput(output)] };
        using var verifier = new PactVerifier("billing-api", config);

        verifier.WithHttpEndpoint(fixture.ServerUri)
                .WithPactBrokerSource(new Uri(Environment.GetEnvironmentVariable("PACT_BROKER_URL")!), o => o
                    .TokenAuthentication(Environment.GetEnvironmentVariable("PACT_BROKER_TOKEN")!)
                    .ConsumerVersionSelectors(new ConsumerVersionSelector { MainBranch = true },
                                              new ConsumerVersionSelector { DeployedOrReleased = true })
                    .PublishResults(Environment.GetEnvironmentVariable("GIT_SHA")!, r => r.ProviderBranch(Environment.GetEnvironmentVariable("GIT_BRANCH")!)))
                .WithProviderStateUrl(new Uri(fixture.ServerUri, "/pact/provider-states"))
                .Verify();
    }
}

// Test-only endpoint in the fixture (never mapped in production builds)
app.MapPost("/pact/provider-states", async (ProviderState s, AppDb db) =>
{
    switch (s.State)
    {
        case "tenant 6f1c… is on the Pro plan":
            await TestData.SeedTenantAsync(db, Guid.Parse("6f1c2a10-0000-4000-8000-000000000001"), plan: "pro"); break;
        case "tenant does not exist":
            break;                                                         // nothing to seed
    }
    return Results.Ok();
});

Provider states هي اللي بتخلي الـ verification مستقلة: كل interaction بتقول «لازم تكون الدنيا كده»، والـ provider بيجهز البيانات دي (DB test أو fakes لـ dependencies بتاعته) قبل ما الـ request يتبعت. ما تحاولش تتحقق ضد بيئة staging مشتركة — البيانات هناك مش تحت سيطرتك.

04

الـ Broker و can-i-deploy: العقد كـ gate

Gating deployments
Deep dive
YAML.github/workflows (excerpts)
# consumer pipeline (ingestion-worker)
- run: dotnet test tests/Ingestion.PactTests           # writes pacts/*.json
- run: pact-broker publish pacts --consumer-app-version $GITHUB_SHA --branch $GITHUB_REF_NAME
- name: can I deploy the worker to production?
  run: pact-broker can-i-deploy --pacticipant ingestion-worker --version $GITHUB_SHA --to-environment production
- run: ./deploy.sh production
- run: pact-broker record-deployment --pacticipant ingestion-worker --version $GITHUB_SHA --environment production

# provider pipeline (billing-api)
- run: dotnet test tests/Billing.PactVerification     # verifies pacts from main + deployed consumer versions
- run: pact-broker can-i-deploy --pacticipant billing-api --version $GITHUB_SHA --to-environment production
  • can-i-deploy بيسأل الـ broker: «النسخة دي اتعمل لها verification ناجح ضد النسخ اللي شغالة دلوقتي في production من كل الـ consumers/providers؟» — لو لأ، الـ deploy بيقف.
  • Webhooks: لما consumer ينشر pact جديد، الـ broker يشغّل verification الـ provider تلقائيًا (فالفريقين بيعرفوا بسرعة).
  • Pending pacts / WIP: توقعات جديدة من consumer ما بتكسرش build الـ provider لحد ما يتحقق منها أول مرة — بيمنع إن فريق يوقف فريق تاني.
05

BDD: Gherkin كلغة مشتركة

Behaviour-driven development
Deep dive

BDD مش أداة؛ هي ممارسة: المطور والـ QA والـ product بيتفقوا على أمثلة محددة للسلوك قبل البناء، ويكتبوها بلغة مفهومة للكل. الأمثلة دي بتبقى acceptance tests قابلة للتنفيذ.

GHERKINFeatures/PlanLimits.feature
Feature: Plan document limits
  Tenants on a plan cannot exceed the plan's document quota,
  but admins see a clear way to upgrade.

  Background:
    Given a tenant "Acme" on the "Starter" plan with a limit of 5 documents
    And "Acme" already has 5 documents

  Scenario: Upload beyond the quota is rejected with an upgrade hint
    When a member of "Acme" uploads a document "policy.pdf"
    Then the upload is rejected with status 402
    And the response includes the meter "documents" and the limit 5
    And no document is stored for "Acme"

  Scenario: Upgrading raises the limit immediately
    Given "Acme" upgrades to the "Pro" plan
    When a member of "Acme" uploads a document "policy.pdf"
    Then the upload is accepted

  Scenario Outline: Quotas per plan
    Given a tenant "T" on the "<plan>" plan with no documents
    When a member of "T" uploads <count> documents
    Then <accepted> uploads are accepted
    Examples:
      | plan    | count | accepted |
      | Starter | 6     | 5        |
      | Pro     | 6     | 6        |
C#StepDefinitions/PlanLimitsSteps.cs (Reqnroll + WebApplicationFactory)
[Binding]
public sealed class PlanLimitsSteps(TestApp app, ScenarioContext ctx)
{
    [Given("a tenant {string} on the {string} plan with a limit of {int} documents")]
    public Task GivenTenantOnPlan(string tenant, string plan, int limit) => app.SeedTenantAsync(tenant, plan, limit);

    [Given("{string} already has {int} documents")]
    public Task GivenExistingDocs(string tenant, int n) => app.SeedDocumentsAsync(tenant, n);

    [When("a member of {string} uploads a document {string}")]
    public async Task WhenUpload(string tenant, string file) =>
        ctx["response"] = await app.ClientFor(tenant, role: "member").PostAsync("/api/documents", TestFiles.Pdf(file));

    [Then("the upload is rejected with status {int}")]
    public void ThenRejected(int status) => Assert.Equal(status, (int)((HttpResponseMessage)ctx["response"]).StatusCode);

    [Then("no document is stored for {string}")]
    public async Task ThenNothingStored(string tenant) => Assert.Equal(5, await app.CountDocumentsAsync(tenant));
}

Reqnroll هو المشروع المفتوح اللي كمّل بعد SpecFlow (اللي وقف تطويره)، ومتوافق معاه بشكل كبير مع migration guide. الـ steps بتستخدم نفس WebApplicationFactory و Testcontainers بتوع الـ integration tests — الـ Gherkin طبقة قراءة فوقهم مش test framework منفصل.

06

إمتى BDD بيستاهل؟

When BDD adds value
Basics
بيستاهلمش بيستاهل
قواعد بيزنس معقدة (billing، صلاحيات، تسعير) والـ product بيقرا ويراجع الـ scenariosمحدش غير المطورين بيقرا الـ feature files
Regulated domains محتاجة توثيق «السلوك المتفق عليه»اختبارات تقنية (retry، caching) — xUnit أوضح
Discovery workshops (Three Amigos) بتطلّع حالات حدودية قبل الكودScenarios مكتوبة بعد الكود كترجمة للـ tests (ceremony)

علامات Gherkin سيء: steps فيها تفاصيل UI («click button id=btn-submit»)، scenarios طويلة 20 خطوة، وصياغة imperative بدل declarative. الكويس: لغة البيزنس، scenario واحد = قاعدة واحدة، وأمثلة بأرقام حقيقية.

07

الـ pipeline الكامل: كل نوع اختبار فين

Putting it in CI
Deep dive
Unitevery push · secsIntegration + BDDPR · TestcontainersContractspublish + verifycan-i-deploygate per envE2E smokeafter deploy+ OpenAPI diff on every PR · AI eval gate for prompt/model changes · nightly full E2E
Fast feedback first; contracts gate deployments; slow suites run where they pay off
  • الـ contract tests مكانها بين الـ integration والـ E2E: أسرع من E2E بكتير، وبتغطي اللي الـ unit مش شايفه.
  • الـ OpenAPI diff والـ Pact مكملين لبعض: الأول بيحمي العملاء اللي مش بيكتبوا pacts (شركاء خارجيين)، والتاني بيحمي الـ consumers الداخليين بسلوكهم الفعلي.
  • Angular كـ consumer: @pact-foundation/pact مع Jest/Vitest بيعمل نفس الشيء من جهة الـ frontend.
08

Contracts للـ messages والـ events

Message pacts
Deep dive

الـ breaking changes في الـ events أخطر من الـ HTTP: الـ consumer مش موجود في نفس اللحظة، والرسايل القديمة لسه في الـ queue. Pact بيدعم message pacts: الـ consumer بيوصف شكل الـ message اللي بيتوقعها (مثلًا DocumentUploaded)، والـ provider بيثبت إن الـ producer code بيطلع message مطابقة.

C#consumer side: the ingestion worker expects DocumentUploaded v1
_pact.ExpectsToReceive("a DocumentUploaded event")
     .Given("a PDF was uploaded")
     .WithJsonContent(new
     {
         type = "document.uploaded", version = Match.Integer(1),
         documentId = Match.Regex("00000000-0000-4000-8000-000000000001", "^[0-9a-f-]{36}$"),
         tenantId = Match.Type("6f1c2a10-0000-4000-8000-000000000001"),
         blobRef = Match.Type("t/6f1c…/raw/abc.pdf"), contentType = Match.Regex("application/pdf", "^[a-z]+/[a-z0-9.+-]+$")
     })
     .Verify<DocumentUploaded>(msg => handler.Validate(msg));    // the real handler's parsing/validation

مع قواعد versioning للـ events (حقول إضافية بس في نفس الـ version، و version جديد للتغيير الكاسر مع دعم القديم لفترة) — زي Messaging.

09

الـ frontend كـ consumer

Angular as a consumer
Practical
TypeScriptdocuments.pact.spec.ts (PactV4 + Vitest; shape)
const provider = new PactV4({ consumer: 'knowledge-web', provider: 'knowledge-api', dir: './pacts' });

it('lists documents for the dashboard', () =>
  provider.addInteraction()
    .given('tenant has 2 ready documents')
    .uponReceiving('a request for the first page of documents')
    .withRequest('GET', '/api/documents', b => b.query({ page: '1' }).headers({ Accept: 'application/json' }))
    .willRespondWith(200, b => b.jsonBody({
      items: eachLike({ id: uuid(), title: like('Leave policy'), status: regex('ready|processing|failed', 'ready') }),
      total: integer(2),
    }))
    .executeTest(async server => {
      const api = new DocumentsApi(createHttpClient(server.url));          // the real Angular service
      const page = await firstValueFrom(api.list(1));
      expect(page.items[0].status).toBe('ready');
    }));

كده لو فريق الـ API غيّر status من string لـ enum رقمي، الـ verification بتاعتهم هتفشل قبل الـ merge، مش الـ dashboard في الإنتاج.

10

أخطاء شائعة

Common mistakes
Basics
  • Pacts بقيم حرفية بدل matchers ← بتتكسر مع أي تغيير بيانات.
  • الـ provider بيكتب الـ pacts بنفسه (provider-driven) — بيفقد فكرة «اللي بيستخدمه الـ consumer فعلًا».
  • Verification ضد staging مشتركة بدل provider states.
  • Pact لاختبار منطق البيزنس الكامل (هو للعقد مش للسلوك الداخلي).
  • Gherkin مكتوب بلغة UI أو بعد الكود من غير ما الـ product يقراه.
  • مفيش can-i-deploy، فالـ pacts بتعدّي بس محدش بيمنع الـ deploy.
11

اختبر فهمك

Knowledge check
Basics

الـ provider عايز يشيل حقل createdAt من الـ response. إزاي يعرف إنه آمن؟

Provider state في Pact معناه؟

12

تمرين محلول

Worked exercise
Practical
صمّم استراتيجية contracts للـ Capstone: Angular ← API، worker ← billing API، API ← LLM provider

الحل: Angular ← API: Pact (JS) على الـ endpoints اللي الـ UI بتستخدمها + OpenAPI diff + types متولدة. worker ← billing: Pact (‎.NET) زي المثال، can-i-deploy على الاتنين. API ← LLM provider: مش ممكن تعمل pact مع طرف تالت مش بيتحقق؛ بدلها: adapter معزول، contract tests ضد mock-llm بنفس شكل الـ API الحقيقي، smoke test يومي ضد الـ provider الحقيقي بمفتاح test، وتثبيت API version. ده بيغطي التلات حدود من غير E2E ضخم.

13

أسئلة إنترفيو

Interview questions
Basics
(Mid) إيه الفرق بين contract test و integration test؟
الـ integration test بيختبر خدمة مع dependencies حقيقية؛ الـ contract test بيختبر إن طرفين متفقين على شكل التفاعل (request/response) كل واحد لوحده: الـ consumer ضد mock، والـ provider ضد العقد المسجل، من غير ما يشتغلوا مع بعض.
(Senior) فريقين بيعطلوا بعض بالـ breaking changes. تعمل إيه؟
Consumer-driven contracts مع broker، verification تلقائي على كل تغيير، can-i-deploy كـ gate، pending pacts عشان التوقعات الجديدة ما توقفش الـ provider، OpenAPI diff للحماية العامة، وسياسة deprecation (حقل جديد ← فترة دعم ← حذف بعد ما الـ broker يوري إن محدش بيستخدم القديم).
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس