Skip to main content
PagrindinisTinklaraštisVadovaiStebėjimo API integracijos testavimas kūrimo aplinkoje: smėlio dėžė, testiniai numeriai, modeliuojami žiniatinklio kabliukai

Stebėjimo API integracijos testavimas kūrimo aplinkoje: smėlio dėžė, testiniai numeriai, modeliuojami žiniatinklio kabliukai

17TRACK

Norėdami kūrimo aplinkoje išbandyti siuntų sekimo API integraciją, naudokite tris viena kitą papildančius metodus: teikėjo smėlio dėžę arba dokumentacijoje nurodytus testinius numerius API veikimui tikrinti, vietinius testinius duomenis pakartojamiems siuntų scenarijams ir imitacinius webhook įvykius jūsų priimančiam endpoint’ui. Tada atlikite kontroliuojamą tiesioginį patikrinimą, kad patvirtintumėte dalis, kurių imitacijos negali įrodyti, įskaitant kredencialus, prenumeratos konfigūraciją ir faktinį įvykių pristatymą.

Testing a Tracking API Integration in Development Sandbox Test Numbers

Šis vadovas skirtas kūrėjams, kurie siuntų sekimą jungia prie el. prekybos platformos, užsakymų valdymo sistemos, ERP arba klientų informavimo paslaugos. Tikslas nėra vien gauti sėkmingą API atsakymą. Reikia įrodyti, kad sekimo atnaujinimai sukuria teisingą užsakymo būseną be pasikartojančių pranešimų, prarastų įvykių ar netyčinio kontakto su tikrais klientais.

Atskirkite teikėjo veikimą nuo programos veikimo

Sekimo integracija turi bent dvi ribas: užklausas, kurias jūsų programa siunčia teikėjui, ir atnaujinimus, kuriuos jūsų programa vėliau gauna arba pasiima. Sėkminga užklausa pirmojoje riboje neįrodo, kad antroji riba veikia.

Testavimo planą kurkite atsižvelgdami į šias ribas, o ne tikėdamiesi, kad vienas testinis sekimo numeris patikrins visą sistemą.

Testavimo metodasKą jis gali patvirtintiKo vienas pats negali įrodyti
Teikėjo smėlio dėžėPalaikomus užklausų formatus, autentifikavimą ir teikėjo aprašytą imituojamą veikimąGamybinių vežėjų duomenų prieinamumo ar gamybinio pristatymo veikimo
Dokumentuoti testiniai numeriaiKonkrečius scenarijus, priskirtus tiems numeriamsKitas būsenas, vežėjus ar webhook įvykių sekas
Vietiniai testiniai duomenys ir API imitacijosJūsų analizatorių, susiejimo taisykles, išsaugojimą ir klaidų tvarkymąAr tikras teikėjas priima užklausas arba siunčia tokį patį turinį
Imitacinės webhook užklausosEndpoint’o apdorojimą, tikrinimą, dublikatų šalinimą ir tolesnį poveikįTeikėjo callback konfigūraciją ar tikrus pakartotinius pristatymus
Kontroliuojamas tiesioginis testasRealų ryšį ir stebimą siuntos procesąKiekvieną retą klaidą, išimtį ar pristatymo seką

Rekomenduojamas metodas: vietinius testus padarykite deterministinius, kai įmanoma, naudokite teikėjo palaikomą testavimą, o tikras siuntas pasilikite sistemų ryšiui patvirtinti.

Prieš kurdami testinius duomenis patvirtinkite teikėjo sutartį

Pradėkite nuo oficialios planuojamos naudoti API versijos dokumentacijos. Patvirtinkite bazinį URL, autentifikavimo metodą, registracijos reikalavimus, atsakymo schemą, webhook nustatymą ir visas dokumentuotas testavimo galimybes. Nemanykite, kad egzistuoja atskira smėlio dėžė vien todėl, kad teikėjas siūlo API.

17TRACK integracijai pradėkite nuo 17TRACK Tracking API puslapio ir oficialios API dokumentacijos. Prieš kurdami konkrečiam teikėjui skirtus pavyzdžius, ten patikrinkite taikomas užklausų ir callback specifikacijas. Toliau pateikti pavyzdžiai yra sąmoningai jūsų programai priklausantys testiniai duomenys, o ne 17TRACK API schemos atvaizdas.

Prieš prijungdami kūrimo kodą prie išorinės paskyros, atsakykite į šiuos klausimus:

  • Ar kūrimo ir gamybos kredencialai yra atskiri ir prie kokios aplinkos suteikia prieigą kiekvienas kredencialas?
  • Ar smėlio dėžė palaiko callback įvykius, ar tik užklausų ir atsakymų testavimą?
  • Ar testiniai numeriai dokumentuoti ir kokius tiksliai rezultatus jie sukuria?
  • Ar registracijos arba kitos testinės užklausos gali naudoti paskyros kvotą arba sukurti nuolatinius įrašus?
  • Kokios callback autentifikavimo, patvirtinimo, skirtojo laiko ir pakartotinio bandymo taisyklės yra dokumentuotos?
  • Kurie identifikatoriai susieja sekimo registraciją, siuntą, vežėją ir callback įvykį?

Jei testavimo elgsena neaiškiai dokumentuota, paprašykite teikėjo ją patvirtinti. Tuo tarpu toliau testuokite savo apdorojimo logiką naudodami imitacijas. Nepatvirtinta smėlio dėžės galimybė yra planavimo neapibrėžtumas, o ne įrodymas, kad teikėjas tokios galimybės neturi.

Sukurkite izoliuotą kūrimo aplinką

Naudokite atskirą duomenų bazę arba izoliuotą nuomininką, atskiras paslaptis ir sintetinius užsakymus. El. laiškus, SMS žinutes ir kitus pranešimus nukreipkite į testavimo paskirties vietas arba pranešimų surinkimo sistemą. Pagal testinius duomenis pažymėta kaip pristatyta siunta neturi sukelti pranešimo tikram pirkėjui.

Į vidinius įrašus ir žurnalus įtraukite aiškų aplinkos žymeklį. Teikėjo kredencialus laikykite serveryje, ne versijų valdymo sistemoje, o paslaptis pašalinkite iš užklausų įrašų. Jei callback įvykiams reikia laikinos viešos prieigos, atverkite tik numatytą kūrimo maršrutą ir išlaikykite jo autentifikavimo kontrolę.

Prieš siųsdami įvykius sukurkite nedidelį žinomų užsakymų rinkinį. Įtraukite dvi siuntas, susietas su vienu užsakymu, ir, jei jūsų programa tai palaiko, tą pačią sekimo numerio eilutę skirtingų vežėjų kontekstuose. Šie atvejai atskleidžia prielaidas, kad vien sekimo numeris visada identifikuoja unikalų verslo įrašą.

Iš anksto apibrėžkite kiekvieno testo laukiamą poveikį: siuntos būseną, užsakymo susiejimą, laiko juostos įrašus, pranešimų skaičių ir audito įrašą. Taip demonstracija tampa teiginiu, kuris gali būti patvirtintas arba atmestas.

Testinius numerius naudokite tik dokumentuotai paskirčiai

Sekimo numeris turi du skirtingus vaidmenis testuojant. Jis gali būti įvestis registracijai tikrinti ir gali identifikuoti siuntą, kuri sukuria sekimo įvykius. Numeris, kuris praeina formato patikrą, nebūtinai suteikia naudingą įvykių istoriją.

Kai yra oficialūs testiniai numeriai

Kartu su kiekvienu numeriu įrašykite teikėjo nurodytą scenarijų. Numerio, dokumentuoto pristatytai siuntai, nereikėtų laikyti išimties, grąžinimo ar nesėkmingo pristatymo bandymo imitacija. Taip pat patikrinkite, ar jo rezultatas nekinta, kinta laikui bėgant arba reikalauja pasirinkti konkretų vežėją.

Laikykite šiuos numerius specialioje integracijos testų konfigūracijoje. Nepaskleiskite jų vienetiniuose testuose, nes pasikeitus išorinei elgsenai kitaip deterministiniai testai gali tapti nepatikimi.

Kai oficialūs testiniai numeriai nepatvirtinti

Naudokite sintetinius identifikatorius savo programoje ir imituokite teikėjo ribą. Niekada nesugalvokite tikroviškai atrodančio numerio manydami, kad jis skirtas testavimui: jis gali sutapti su tikra siunta.

Tiesioginiam tikrinimui naudokite siuntas, kurias kontroliuojate ir prie kurių turite teisę prieiti. Nekopijuokite sekimo numerių iš viešų ekrano kopijų ar klientų pokalbių. Siuntų istorijas laikykite potencialiai jautriomis, nes jose gali būti vietų, laiko žymų ir pristatymo informacijos.

Senesnė pristatyta siunta gali padėti patikrinti analizavimą, tačiau ji yra prasta nuolatinės integracijos priklausomybė. Istorinių duomenų prieinamumas ir išorinis atsakymas gali pasikeisti. Išsaugokite nuasmenintus testinius duomenis pakartojamiems testams, o tiesioginį patikrinimą vykdykite atskirai.

Kurkite testinius duomenis pagal prasmingus siuntos būsenų pokyčius

Testinius duomenis kurkite pagal dokumentuotą schemą ir, kai įmanoma, nuasmenintus tikrus atsakymus. Teikėjo turinio testinius duomenis laikykite atskirai nuo vidinio normalizuoto įvykio modelio. Testuokite adapterį tarp jų, kad vidinė imitacija nepaslėptų sugedusio teikėjo analizatoriaus.

Naudingas pradinis rinkinys apima šiuos scenarijus:

  • Kol kas nėra sekimo įvykių: išsaugokite siuntą neteigdam i, kad ji juda arba pristatyta.
  • Vežama: atnaujinkite laiko juostą ir išsaugokite teisingą užsakymo susiejimą.
  • Pristatyti bandoma: taikykite pranešimų politiką nelaikydami, kad pristatymas baigtas.
  • Pristatyta: užregistruokite pabaigą ir vieną kartą sukurkite numatytą verslo veiksmą.
  • Išimtis arba bandymas pristatyti: išlaikykite skirtumą nuo užbaigto pristatymo.
  • Grąžinimo judėjimas: nelaikykite kiekvieno vėlesnio skenavimo progresu link pradinio gavėjo.
  • Nežinoma būsena: išsaugokite pakankamai informacijos diagnozei, nesukurdami išgalvoto būsenos susiejimo.

Šiems scenarijams naudokite savo normalizuotus pavadinimus, tada aiškiai susiekite dokumentuotas teikėjo reikšmes su jais. Nemanykite, kad skirtingos API naudoja tas pačias būsenų etiketes arba kad etiketė visur turi vienodą verslo reikšmę.

Taip pat keiskite duomenų struktūrą: tuščias įvykių sąrašas, trūkstami pasirenkami laukai, papildomi nežinomi laukai, unikodo vietų pavadinimai, laiko žymos su laiko juostos poslinkiais ir netinkamos privalomos reikšmės. Jūsų analizatorius turi toleruoti suderinamus papildymus, bet atmesti duomenis, kurių negalima saugiai apdoroti.

Siųskite imitacinius webhook įvykius per tikrą priėmimo kelią

Imitacinis webhook įvykis turi patikrinti priėmimo maršrutą, autentifikavimo tarpinę programinę įrangą, validavimą, saugojimą ir darbuotojo apdorojimą, o ne tik iškviesti galutinę būsenos atnaujinimo funkciją.

Toliau pateiktas turinys vaizduoja sintetinį vidinį įvykį. Laukų pavadinimai, įvykio ID ir būsena yra iliustraciniai; jie nėra teikėjo callback sutartis.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Išsaugokite jį kaip tracking-event.json ir nusiųskite į vietinį testavimo imtuvą:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

Ši komanda tikrina tik vietinį maršrutizavimą ir apdorojimą. Ji neįrodo teikėjo autentifikavimo. Kūrimo aplinkai skirtą maršrutą laikykite nepasiekiamą gamyboje arba tikrinkite gamybinį imtuvą naudodami teikėjo dokumentuotą autentifikavimo metodą ir atskirą testinę paslaptį.

Testuokite autentifikavimą nesilpnindami gamybos kontrolės

Jei teikėjas nurodo pasirašytus callback įvykius, įgyvendinkite būtent tą schemą, o ne savavališkai pasirinkite parašo antraštę ar algoritmą. Schemoje, kurioje pasirašomi užklausos baitai, išsaugokite pradinį turinį tikrinimui; JSON analizavimas ir pakartotinis serializavimas gali pakeisti šiuos baitus.

Jei taikoma, testuokite galiojantį autentifikavimą, trūkstamus kredencialus, pakeistą turinį ir neteisingus parašus. Jei dokumentuotoje schemoje yra laiko žymos arba pakartojimo apsauga, patikrinkite ir šias taisykles. HMAC yra standartizuota pranešimų autentifikavimo konstrukcija, tačiau vien jos egzistavimas neįrodo, kad konkretus sekimo teikėjas ją naudoja.

Testuokite dublikatus, tvarką ir atkūrimą

Siuntų apdorojimas turi išlikti teisingas, kai tas pats atnaujinimas gaunamas kelis kartus arba įvykiai gaunami netikėta tvarka. Tai yra gynybinio testavimo scenarijai, o ne teiginiai apie konkretaus teikėjo pristatymo garantijas.

TestasTikėtina programos elgsena
Du kartus siųsti tą patį įvykįIšlaikyti vieną loginį įvykį ir išvengti pasikartojančių klientų pranešimų.
Po pristatymo siųsti senesnį tranzito skenavimąIšsaugoti naudingą istoriją automatiškai neatšaukiant pristatytos būsenos.
Siųsti vienu metu gaunamus atnaujinimusTaikyti nuoseklius būsenų pokyčius nepaisant lygiagrečių darbuotojų.
Nutraukti apdorojimą po patvaraus gavimoAtkurti ir apdoroti išsaugotą įvykį nereikalaujant naujo callback.
Saugyklos klaida prieš patvarų gavimąMelagingai nepatvirtinti sėkmingo priėmimo.
Siųsti nežinomą siuntąTaikyti apibrėžtą izoliavimo arba atmetimo politiką; niekada neatspėti užsakymo susiejimo.

Jei jis pateikiamas, dublikatams šalinti pirmenybę teikite dokumentuotam stabiliam įvykio identifikatoriui. Priešingu atveju apibrėžkite kruopščiai apribotą tapatybę pagal susijusius laukus ir testuokite susidūrimus. Vien sekimo numeris nėra įvykio tapatybė, nes viena siunta gali sukurti daug teisėtų atnaujinimų.

Įvykių istoriją atskirkite nuo dabartinės siuntos projekcijos. Istorinių skenavimų saugojimas nereiškia, kad kiekvienas vėluojantis skenavimas turi perrašyti rodomą būseną. Taisyklė „naudoti naujausią laiko žymą“ taip pat nėra išsami: pataisoms, grąžinimo procesams ir skirtingoms laiko žymų reikšmėms reikia aiškaus apdorojimo.

Asinchroniniame apdorojime patvirtinkite tik tada, kai įvykis pasiekia patvarų perdavimo tašką, pavyzdžiui, patvirtintą inbox įrašą arba patvarią eilę, atsižvelgiant į jūsų architektūrą. Laikykitės teikėjo dokumentuotų patvirtinimo reikalavimų. HTTP apibrėžia būsenos kodo semantiką, tačiau konkretaus siuntėjo pakartotinių bandymų tvarkaraštis turi būti nustatytas jo sutartyje.

Atlikite kontroliuojamą tiesioginį patikrinimą ir nustatykite išleidimo kriterijus

Kai deterministiniai testai praeina, per tikrą integraciją užregistruokite autorizuotą siuntą ir patvirtinkite visą kelią. Patikrinkite, ar teikėjas priėmė numatytą įrašą, ar callback konfigūracija nurodo teisingą aplinką ir ar gaunami duomenys susiejami su numatyta siunta.

Nereikalaukite, kad tiesioginio patikrinimo metu pasirodytų kiekviena siuntos būsena. Tikros siuntos nėra kontroliuojami testiniai duomenys. Tiesioginį vykdymą naudokite ryšiui ir stebimam sutarties suderinamumui patvirtinti, o retus arba destruktyvius scenarijus tikrinkite pakartojamais testiniais duomenimis.

Prieš išleidimą reikalaukite šių rezultatų:

  • Apdorojami dokumentuoti sėkmės ir klaidų atsakymai, įskaitant atskirų elementų klaidas, jei API palaiko paketines operacijas.
  • Skirtojo laiko pabaiga nesukelia aklo kūrimo pakartojimo, kai pirmoji užklausa galėjo būti jau sėkminga.
  • Dublikatų įvykiai negali sukurti pasikartojančių verslo veiksmų.
  • Netinkami callback įvykiai negali pakeisti siuntos būsenos.
  • Darbuotojo klaidos palieka atkuriamus įvykius, o ne tyliai juos praranda.
  • Kūrimo srautas negali informuoti tikrų klientų ar keisti gamybinių užsakymų.
  • Žurnalai susieja užklausas, gautus įvykius, apdorojimo rezultatus ir bandymus siųsti pranešimus neatskleisdami paslapčių.

Išleidimas paruoštas, kai galite paaiškinti įprastą procesą ir tai, kaip sistema atsigauna po neaiškios užklausos, pasikartojančio callback arba nutraukto darbuotojo darbo. Vieno sėkmingo sekimo patikrinimo nepakanka.

DUK

Ar galiu testuoti sekimo integraciją be smėlio dėžės?

Taip. Imituokite siunčiamų API užklausų ribą, atkurkite dokumentuotus callback testinius duomenis ir vietoje testuokite normalizavimą bei verslo taisykles. Tada naudokite autorizuotą tiesioginę siuntą faktiniam ryšiui patvirtinti. Tai suteikia didelę aprėptį, tačiau neatkuria nedokumentuoto teikėjo elgesio.

Kodėl mano sekimo užklausa sėkminga, bet negrąžinami jokie įvykiai?

Užklausos priėmimas ir sekimo duomenų prieinamumas yra skirtingi rezultatai. Patikrinkite teikėjo atsakymo informaciją, registracijos reikalavimus, vežėjo identifikavimo taisykles ir dokumentuotą elgesį su siuntomis, neturinčiomis įvykių. Nekurkite judėjimo ar pristatymo informacijos, kad užpildytumėte tuščią laiko juostą.

Ar sėkmingas imitacinis webhook įvykis įrodo, kad tikri webhook įvykiai bus gauti?

Ne. Jis įrodo tik imitacijos patikrintą kelią. Tikras pristatymas taip pat priklauso nuo teikėjo konfigūracijos, viešo pasiekiamumo, TLS, autentifikavimo ir faktinės callback sutarties. Patvirtinkite tai naudodami teikėjo palaikomą bandomąjį pristatymą arba autorizuotą tiesioginį procesą.

Ar turėčiau grąžinti HTTP 200 prieš baigiant apdorojimą?

Laikykitės teikėjo dokumentuotos patvirtinimo sutarties. Asinchroninėje architektūroje patvirtinkite po patvaraus priėmimo, o tada apdorokite darbuotojui. Sėkmės grąžinimas prieš patvarų priėmimą gali prarasti įvykį, jei procesas netrukus nutrūks.

Kaip turėčiau testuoti klientų pranešimus?

Visus kūrimo aplinkos pranešimus siųskite į kontroliuojamą surinkimo sistemą. Patikrinkite gavėją, šabloną, sužadinantį būsenos pokytį ir siuntimų skaičių. Pakartokite tą patį įvykį ir imituokite darbuotojo pakartotinius bandymus, kad įsitikintumėte, jog vienas siuntos atnaujinimas nesukuria pasikartojančių klientų pranešimų.

Šaltiniai

  • 17TRACK Tracking API — oficialus pradinis taškas sekimo API produktui.
  • 17TRACK API dokumentacija — teikėjui skirtos integracijos sutarties nuoroda; čia patvirtinkite taikomus testavimo ir callback reikalavimus.
  • RFC 9110: HTTP Semantics — HTTP atsakymų semantika ir užklausų pakartotinio siuntimo aspektai.
  • RFC 2104: HMAC — standartizuota pranešimų autentifikavimo konstrukcija, aptariama callback saugumo gairėse.