Schrijver: Max van Deursen, Software Engineer
Laatst werkte ik aan een nieuwe koppeling tussen mijn app en een extern systeem om klantdata op te halen. Op basis van de API-specificatie bouwde ik de integratie, testte alles lokaal met een fake implementatie, en het leek perfect te werken. Mijn code ging door de review, ik zette ’m live… en toen… BAM, ging het mis. De echte API reageerde anders dan verwacht.
Waarom zag ik dit niet eerder? Was mijn fake implementatie te beperkt? Of week de provider af van de specificatie, of was dit allebei zelfs het geval?
Die fout zette me aan het denken: dit moet beter kunnen. In deze blogserie neem ik je mee in de wereld van contract testing; een techniek waarmee je dit soort integratie-issues al vroeg kunt tackelen. Met contact testing vind je deze gevallen al voordat de systemen überhaupt direct met elkaar verbonden zijn. Hoe eerder je de fouten vindt, hoe minder impact ze maken.
De provider en de consumer
In contract testing worden de systemen die met elkaar communiceren vaak de provider en de consumer genoemd. De provider is het systeem wat functionaliteit en data aanbiedt die andere systemen kunnen gebruiken. Een voorbeeld hiervan is een REST API waarmee je productgegevens kunt opvragen. De consumer is het systeem dat de provider uitvraagt om zijn werk te doen. Een webshop die productgegevens toont is een voorbeeld van zo’n consumer.
De afspraken
De consumer wilt weten hoe deze met de provider kan communiceren en wat deze aanbiedt. Ook heeft de consumer behoefte om goed te weten waar de provider aan dient te voldoen.
Om vervelende verrassingen te voorkomen bij het koppelen van de systemen is het handig om deze functionaliteit en behoeftes van de provider en consumer vast te leggen. In het geval van communicatie met behulp van HTTP is de OpenAPI Specification (OAS) een veelvoorkomend formaat om dit te documenteren. Met de OAS kan je een HTTP API omschrijven zonder dat er toegang tot de broncode, documentatie, of netwerkverbinding nodig is. Deze specificatie biedt de provider een handvat om zijn implementatie in te richten. Ook de consumer kan beginnen met ontwikkelen op basis van deze specificatie.
Afspraken nakomen
Tijdens het ontwikkelen van zowel de consumer als provider wordt er gekeken naar de OAS. De provider zorgt dat zijn REST endpoints overeenkomen met de OAS. De consumer maakt een fake implementatie van de provider om zo de reactie van zijn systeem te testen.
Deze ontwikkeling heeft de beste intenties, maar toch kunnen er fouten voorkomen. Hier komt contract testing om de hoek kijken. Deze tests bevestigen dat de provider zich aan de afspraken houdt en dat de implementatie van de consumer alleen de OAS gebruikt.
Gelukkig bestaat er software die ons bij deze opzet kan helpen. Ik heb goede ervaringen met de tool Specmatic om dit allemaal (en meer) mogelijk te maken en dit is dan ook de tool die ik in deze blogreeks gebruik.
Specmatic
Specmatic is software waarmee je zowel de consumer als provider kunt contract testen. Bij het testen met behulp van Specmatic staat de OAS centraal. Voor de consumer biedt Specmatic een “Smart Mock” server aan. Deze server kan de consumer gebruiken als fake implementatie van de provider. De reacties die deze server geeft worden aan de hand van de OAS gegenereerd. Ook biedt Specmatic de mogelijkheid zelf voorbeelden mee te geven als reactie. Voordat deze worden gebruikt, worden deze voorbeelden eerst gevalideerd aan de hand van de OAS. Hierdoor kan de consumer zeker zijn dat zijn implementatie overeenkomt met de OAS en aan de hand van de voorbeelden kunnen alle edge cases worden afgedekt.
Specmatic kan ook de provider testen aan de hand van de OAS. Net zoals bij de consumer genereert Specmatic zelf testen op basis van de OAS. Ook hier biedt Specmatic de mogelijkheid om voorbeelden mee te geven die moeten worden getest. Hierna worden de antwoorden van de provider geverifieerd of zij overeenkomen met de omschreven structuur in de OAS.
Wat nu?
Omdat zowel de consumer als de provider gebruik maken van dezelfde OAS en hier beide op getoetst zijn, zal de daadwerkelijke communicatie ook volgens dezelfde specificatie verlopen. Hiermee ben je zeker van het functioneren van jouw applicatie, zelfs zonder dat de echte API is gebruikt! Daarnaast kan je met de voorbeelden specifieke gevallen nabootsen en zo ook de edge cases van jouw applicatie testen.
Met contract testing weet je zeker dat systemen doen wat ze beloven, nog voor ze echt met elkaar praten. Dat voorkomt verrassingen en maakt samenwerken aan API’s betrouwbaarder en sneller. Wil je weten hoe je dit voor een consumer opzet? In de volgende blog uit deze reeks neem ik je mee om dit met behulp van Specmatic te implementeren. Zo kan jij er ook binnen jouw project voor zorgen dat je voordeel van Specmatic hebt!
Overzicht blogreeks
19 augustus 2025 – Contract Testing: Integratieproblemen vroeg opgelost
21 oktober 2025 – Implementeer contract testing als Consumer met Specmatic
23 december 2025 – Valideer je API implementatie met behulp van Specmatic
17 februari 2026 – Beheer van OpenAPI specificaties en veilig wijzigen met Specmatic
