Makiety, stuby, atrapy i emulatory: testowanie wywołań interfejsu API za pomocą agentów kodowania

Gdy kod wywołuje interfejs API, potrzebujesz sposobu, aby go przetestować bez czekania, aż prawdziwy interfejs API ulegnie awarii. Masz do wyboru 5 rodzajów dublerów. Ludzie dość swobodnie używają tych terminów, więc w tym artykule są one używane w następującym znaczeniu:

Stub: zamiennik działający w tym samym procesie dla klienta HTTP lub wywołania SDK, który zwraca gotową odpowiedź. Jest szybki i powtarzalny oraz testuje logikę zawartą w napisanej przez Ciebie odpowiedzi.
Mock: atrapa, która również rejestruje sposób, w jaki kod ją wywoływał, aby test mógł sprawdzić wywołania. Sięga aż do zaślepki.
Pozorowany serwer: niewielki, działający serwer, często działający w pamięci, z którym aplikacja komunikuje się przez HTTP zamiast z prawdziwym interfejsem API. Testuje klienta HTTP, ale musisz skierować aplikację na jego adres URL.
Emulator: lokalna wersja usługi, zwykle opublikowana przez właściciela usługi, która działa jak rzeczywista usługa dla operacji, które obsługuje. Sprawdź, jakie limity i awarie obejmuje, zanim zaczniesz na nim polegać przy obsłudze błędów.
Serwer proxy przechwytujący: znajduje się w sieci między aplikacją a interfejsem API. Aplikacja wywołuje rzeczywisty adres URL, a serwer proxy przepuszcza żądania dalej lub odpowiada na niektóre z nich zdefiniowaną odpowiedzią. Aplikacja musi wysyłać ruch przez serwer proxy i w przypadku protokołu HTTPS ufać certyfikatowi serwera proxy.

Jak przetestować kod wywołujący interfejs API

Approach	Co testuje	Co jest potrzebne	Właśnie gdy
Stub lub mock	Twoja logika dla określonej odpowiedzi	Twój framework testowy	Testujesz logikę biznesową, parsowanie i gałęzie błędów w testach jednostkowych
Fałszywy serwer	Twój klient HTTP i serializacja	Ustawienie bazowego adresu URL lub przełącznik konfiguracji w aplikacji	Interfejs API jeszcze nie istnieje lub potrzebujesz stabilnego zaplecza do pracy interfejsu użytkownika
Emulator	Zachowanie zbliżone do rzeczywistej usługi dla obsługiwanych operacji	Inny punkt końcowy lub parametry połączenia	Właściciel usługi dostarcza jedno rozwiązanie, a Ty rozwijasz je w trybie offline
Rzeczywisty interfejs API z kontem testowym	Prawdziwy oryginał	Dane uwierzytelniające, limit i pieniądze	Weryfikujesz główną ścieżkę od początku do końca
Przechwytujący serwer proxy	Twoja działająca aplikacja pod rzeczywistymi adresami URL, w tym ponowienia żądań przez SDK i nagłówki odpowiedzi	Ustawienia serwera proxy i zaufanie certyfikatu	Testujesz awarie, limity i opóźnienia bez zmieniania aplikacji

Potrzebujesz więcej niż 1 z nich. Atrapy pozwalają utrzymać szybkie testy jednostkowe. Serwer proxy pokazuje, co robi cała aplikacja, gdy rzeczywisty interfejs API działa nieprawidłowo. Aby uzyskać więcej informacji na temat tego, jak te 2 ze sobą współgrają, zobacz Dev Proxy vs unit tests.

Co tworzą agenty programistyczne

Gdy poprosisz agenta kodowania, aby aplikacja zaczęła obsługiwać błędy interfejsu API i pokazała, że działa, wybiera stand-in dla Ciebie. Chcieliśmy wiedzieć, który z nich, więc przeprowadziliśmy test z 3 agentami kodowania (210 przebiegów). W zadaniach używano fraz takich jak „właściwie obsłużyć ograniczanie szybkości i pokaż mi, że to działa”, „zweryfikować to bez wydawania pieniędzy na rzeczywiste wywołania interfejsu API” oraz „uruchom to bez klucza OpenAI lub połączenia internetowego”.

W 76% ze 140 przebiegów, które wymagały działającego kodu, agent ręcznie odtworzył błąd: stuby fetch, httpx.MockTransport lub tymczasowy serwer HTTP.
W 61 z 105 uruchomień w aplikacjach, które wywołują GitHub, OpenAI lub API pogodowe, agent dodał do aplikacji bazowy adres URL lub przełącznik konfiguracji, aby mogła łączyć się z ich fałszywym odpowiednikiem.
W 75 uruchomieniach, w których rzeczywisty interfejs API był dostępny, a monit go nie wykluczał, w 0 z nich przetestowano aplikację pod rzeczywistym adresem URL interfejsu API.

Zaślepki są rozsądnym wyborem dla testów jednostkowych. Luka to to, co pomijają. Stub agenta zwraca błąd oczekiwany przez agenta, który może być niezgodny z tym, co wysyła interfejs API. I przełącznik, który dodał, aby dotrzeć do fałszywych statków za pomocą twojej aplikacji.

Jak pracować z testami Twojego agenta

Zachowaj zaślepki dla swojej logiki. Są one szybkie i testują gałęzie, które napisał agent.
Poproś o faktyczny format błędu. Poproś agenta, aby opierał każdy symulowany błąd na udokumentowanych kodach stanu, nagłówkach i polach treści dostawcy. Nagie 429 nie sprawdza, czy aplikacja odczytuje retry-after lub informuje o błędzie rozliczeniowym z limitu szybkości.
Przejrzyj przełączniki dodane do testów. Jeśli agent dodaje ustawienie podstawowego adresu URL tylko po to, aby testy mogły połączyć się z atrapą, zdecyduj, czy to ustawienie ma być w kodzie produkcyjnym.
Uruchom aplikację raz na rzeczywistych adresach URL z symulowanymi błędami. Przed wysłaniem sprawdź, co działa aplikacja, jej zestaw SDK i zasady ponawiania prób, korzystając z własnych błędów interfejsu API. Aby zapoznać się z obsługą błędów agenta krok po kroku, zobacz Jak zweryfikować błędy obsługi napisanego agenta kodowania.

Wypróbuj ją w aplikacji

Dev Proxy jest serwerem proxy przechwytującym na potrzeby programowania. Zwraca ona odpowiedzi, które definiujesz dla adresów URL, które już wywołuje aplikacja, bez zmian w kodzie aplikacji. Włącz wtyczkę MockResponsePlugin w swojej konfiguracji, devproxyrc.json:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "MockResponsePlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "mocksPlugin"
    }
  ],
  "urlsToWatch": [
    "https://api.contoso.com/*"
  ],
  "mocksPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/mockresponseplugin.schema.json",
    "mocksFile": "mocks.json"
  }
}

Następnie zdefiniuj odpowiedź w mocks.json. To zwraca 503 z nagłówkiem Retry-After dla punktu końcowego prognozy:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://api.contoso.com/v1/forecast*",
        "method": "GET"
      },
      "response": {
        "statusCode": 503,
        "headers": [
          {
            "name": "Retry-After",
            "value": "10"
          }
        ],
        "body": {
          "error": "Service unavailable"
        }
      }
    }
  ]
}

Uruchom Dev Proxy i uruchom aplikację w zwykły sposób:

devproxy --config-file devproxyrc.json

Żądania, które nie pasują do mocka, przechodzą do rzeczywistego interfejsu API. Jeśli potrzebujesz zaplecza, które jeszcze nie istnieje, crudApiPlugin symuluje interfejs API CRUD z danymi w pamięci. Aby losowy udział żądań nie powiódł się zamiast za każdym razem, zobacz Testowanie aplikacji przy użyciu błędów losowych. Aby zainstalować Dev Proxy, zobacz Set up Dev Proxy.

Następne kroki

Symulowane odpowiedzi

Informacje dodatkowe

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-10-05