Skip to main content
ДомаБлогВодичиТестирање на интеграција на API за следење во развојна околина: sandbox, тест-броеви, симулирани webhook-ови

Тестирање на интеграција на API за следење во развојна околина: sandbox, тест-броеви, симулирани webhook-ови

17TRACK

За тестирање интеграција со API за следење во развојна околина, користете три комплементарни методи: sandbox на давателот или документирани тест-броеви за однесувањето на API-то, локални фикстури за повторливи сценарија со пратки и лажни webhook-барања за вашата приемна крајна точка. Потоа извршете контролирана проверка во живо за да ги потврдите деловите што симулациите не можат да ги докажат, вклучувајќи ги акредитивите, конфигурацијата на претплатата и вистинската испорака на настаните.

Тестирање интеграција со API за следење во развојна Sandbox околина и тест-броеви

Овој водич е наменет за програмери кои го поврзуваат следењето на пратки со платформа за е-трговија, систем за управување со нарачки, ERP или услуга за известување на клиенти. Целта не е едноставно да се прими успешен одговор од API-то. Треба да се докаже дека ажурирањата на следењето создаваат точна состојба на нарачката без дупликатни пораки, изгубени настани или случаен контакт со реални клиенти.

Одделете го однесувањето на давателот од однесувањето на апликацијата

Интеграцијата за следење има најмалку две граници: барањата што вашата апликација ги испраќа до давателот и ажурирањата што вашата апликација ги прима или ги презема потоа. Успешното барање на првата граница не докажува дека втората граница функционира.

Направете го планот за тестирање околу овие граници, наместо да очекувате еден тест-број за следење да го провери целиот систем.

Метод на тестирањеШто може да потврдиШто не може самостојно да утврди
Sandbox на давателотПоддржани формати на барања, автентикација и симулирано однесување опишано од давателотДостапност на податоци од производствени превозници или однесување при производствена испорака
Документирани тест-броевиКонкретните сценарија доделени на тие броевиДруги статуси, превозници или секвенци на webhook-настани
Локални фикстури и API mock-тестовиВашиот парсер, правилата за мапирање, зачувувањето и обработката на грешкиДали вистинскиот давател прифаќа барања или испраќа ист payload
Лажни webhook-барањаОбработка на крајната точка, валидација, дедупликација и ефекти врз следните процесиКонфигурација на повратните повици кај давателот или реални повторувања при испорака
Контролиран тест во живоРеална поврзаност и набљудуваниот тек на праткатаСекоја ретка грешка, исклучок или секвенца на испорака

Препорачан пристап: локалните тестови нека бидат детерминистички, користете тестирање поддржано од давателот каде што е достапно и резервирајте ги пратките во живо за потврдување на врската меѓу системите.

Потврдете го договорот со давателот пред да пишувате фикстури

Започнете со официјалната документација за верзијата на API-то што планирате да ја користите. Потврдете ја основната URL-адреса, методот на автентикација, барањата за регистрација, шемата на одговорот, поставувањето на webhook-от и сите документирани можности за тестирање. Не претпоставувајте дека постои одделен sandbox само затоа што давателот нуди API.

За интеграција со 17TRACK, користете ги страницата на 17TRACK Tracking API и официјалната документација за API како почетни точки. Таму проверете ги применливите спецификации за барањата и повратните повици пред да изградите примери специфични за давателот. Примерите подолу намерно се фикстури управувани од апликацијата, а не претстави на шемата на API-то на 17TRACK.

Разрешете ги овие прашања пред да го поврзете развојниот код со надворешна сметка:

  • Дали развојните и производствените акредитиви се одделни и до која околина овозможува пристап секој акредитив?
  • Дали sandbox поддржува повратни повици или само тестирање со барање-одговор?
  • Дали тест-броевите се документирани и какви точни резултати создаваат?
  • Дали регистрациите или другите тест-барања можат да ја трошат квотата на сметката или да создаваат трајни записи?
  • Кои правила за автентикација на повратни повици, потврда, истек на време и повторување се документирани?
  • Кои идентификатори поврзуваат регистрација за следење, пратка, превозник и настан на повратен повик?

Ако однесувањето при тестирање не е јасно документирано, побарајте од давателот да го потврди. Во меѓувреме, продолжете со тестирање на сопствената логика за обработка со mock-тестови. Непотврдена можност на sandbox-от е неизвесност во планирањето, а не доказ дека давателот ја нема таа можност.

Изградете изолирана развојна околина

Користете одделна база на податоци или изолиран tenant, одделни тајни и синтетички нарачки. Е-поштата, SMS-пораките и другите известувања насочете ги кон тестни дестинации или кон систем за прием на известувања. Пратка означена како доставена во фикстура не смее да предизвика порака до вистински купувач.

Додајте експлицитна ознака на околината во внатрешните записи и логови. Чувајте ги акредитивите на давателот на серверот, надвор од контролата на изворниот код, и отстранувајте ги тајните од снимките на барањата. Ако е потребен привремен јавен пристап за повратни повици, изложете ја само предвидената развојна рута и задржете ги нејзините контроли за автентикација.

Создајте мал сет познати нарачки пред да испратите настани. Вклучете две пратки поврзани со една нарачка и, ако вашата апликација го поддржува тоа, истата низа за број на следење под различни контексти на превозник. Овие случаи откриваат претпоставки дека самиот број за следење секогаш идентификува единствен деловен запис.

Однапред дефинирајте го очекуваниот ефект од секој тест: состојбата на пратката, поврзаноста со нарачката, записите во временската линија, бројот на известувања и записот за ревизија. Така демонстрацијата станува тврдење што може да помине или да не помине.

Користете ги тест-броевите само за нивната документирана намена

Бројот за следење има две различни улоги при тестирањето. Може да биде влез што се користи за потврдување на регистрацијата, а може и да идентификува пратка што создава настани за следење. Број што поминува валидација на форматот не мора да обезбедува корисна историја на настани.

Кога се достапни официјални тест-броеви

Запишете го сценариото наведено од давателот покрај секој број. Број документиран за доставена пратка не треба да се смета дека симулира исклучок, враќање или неуспешен обид за достава. Проверете и дали резултатот е фиксен, се менува со текот на времето или бара избор на конкретен превозник.

Чувајте ги овие броеви во посебна конфигурација за интеграциски тестови. Не ги распрскувајте низ unit-тестовите, каде што промената на надворешното однесување може да ги направи инаку детерминистичките тестови несигурни.

Кога официјалните тест-броеви не се потврдени

Користете синтетички идентификатори во сопствената апликација и симулирајте ја границата со давателот. Никогаш не измислувајте број што изгледа веродостојно и не претпоставувајте дека е резервиран за тестирање: може да се совпаѓа со реална пратка.

За валидација во живо, користете пратки што ги контролирате и за кои сте овластени да пристапувате. Избегнувајте копирање броеви за следење од јавни снимки на екранот или разговори со клиенти. Сметајте ги историите на пратките за потенцијално чувствителни бидејќи може да содржат локации, временски ознаки и информации за доставата.

Постара доставена пратка може да помогне при потврдување на парсирањето, но е лоша зависност за континуирана интеграција. Достапноста на историските податоци и надворешниот одговор може да се променат. Зачувајте санирана фикстура за повторливи тестови и одделете ја проверката во живо.

Создавајте фикстури околу значајни премини на пратката

Создавајте фикстури од документираната шема и, кога е достапно, од санирани реални одговори. Чувајте ги фикстурите со payload-и од давателот одделно од вашиот внатрешен нормализиран модел на настани. Тестирајте го адаптерот меѓу нив за внатрешниот mock да не крие неисправен парсер на давателот.

Корисен почетен сет ги опфаќа следните сценарија:

  • Сè уште нема настани за следење: задржете ја пратката без да тврдите дека се движи или дека е доставена.
  • Во транзит: ажурирајте ја временската линија и зачувајте ја точната поврзаност со нарачката.
  • На достава: применете ја политиката за известување без да ја третирате доставата како завршена.
  • Доставено: запишете го завршувањето и емитувајте ја предвидената деловна активност еднаш.
  • Исклучок или обид за достава: зачувајте ја разликата во однос на завршената достава.
  • Движење при враќање: избегнувајте секое подоцнежно скенирање да го толкувате како напредок кон првичниот примател.
  • Непознат статус: зачувајте доволно информации за дијагностика без измислување мапирање на статус.

Користете сопствени нормализирани имиња за овие сценарија, а потоа експлицитно мапирајте ги документираните вредности на давателот кон нив. Не претпоставувајте дека различни API-ја ги користат истите ознаки за статус или дека една ознака има исто деловно значење насекаде.

Исто така менувајте ја структурата на податоците: празна листа на настани, полиња што недостасуваат, дополнителни непознати полиња, имиња на локации во Unicode, временски ознаки со отстапувања од временската зона и неисправни задолжителни вредности. Вашиот парсер треба да толерира компатибилни дополнувања, а да ги одбива податоците што не можат безбедно да се обработат.

Испраќајте лажни webhook-и низ вистинската приемна патека

Лажниот webhook треба да ја активира приемната рута, middleware-от за автентикација, валидацијата, складирањето и обработката од worker, а не само да ја повика конечната функција за ажурирање на статусот.

Следниот payload претставува синтетички внатрешен настан. Имињата на полињата, ID-то на настанот и статусот се илустративни; тие не се договор за повратен повик од давателот.

{
  "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"
}

Зачувајте го како tracking-event.json и испратете го до локален тестен приемник:

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

Оваа команда го потврдува само локалното насочување и обработка. Таа не ја демонстрира автентикацијата со давателот. Развојната рута нека биде недостапна во продукција или тестирајте го продукцискиот приемник со документираниот метод на автентикација на давателот и одделна тестна тајна.

Тестирајте ја автентикацијата без ослабување на продукциските контроли

Ако давателот специфицира потпишани повратни повици, имплементирајте ја токму таа шема наместо произволно заглавје или алгоритам за потпис. Кај шемите што ги потпишуваат бајтовите на барањето, зачувајте го оригиналното тело за верификација; парсирањето и повторното серијализирање на JSON може да ги промени тие бајтови.

Тестирајте валидна автентикација, акредитиви што недостасуваат, изменети тела и неточни потписи каде што е применливо. Ако документираната шема вклучува временски ознаки или заштита од повторување, тестирајте ги и тие правила. HMAC е стандардизирана конструкција за автентикација на пораки, но неговото постоење не докажува дека конкретен давател на следење го користи.

Тестирајте дупликати, редослед и обновување

Обработката на пратките треба да остане исправна кога истото ажурирање пристигнува повеќепати или настаните пристигнуваат по неочекуван редослед. Ова се дефанзивни тест-сценарија, а не тврдења за гаранцијата за испорака на конкретен давател.

ТестОчекувано однесување на апликацијата
Испратете го истиот настан двапатиЗадржете еден логички настан и избегнете дупликатни известувања до клиентите.
Испратете постаро транзитно скенирање по доставатаЗачувајте корисна историја без автоматски да ја враќате состојбата од „доставено“.
Испратете истовремени ажурирањаПрименете конзистентни премини на состојбата и покрај истовремените worker-и.
Запрете ја обработката по траен приемОбновете ја и обработете ја зачуваната настан без да барате нов повратен повик.
Складирањето нека откаже пред приемот да стане траенНе потврдувајте лажно успешно прифаќање.
Испратете непозната праткаСледете дефинирана политика за карантин или одбивање; никогаш не погодувајте ја поврзаноста со нарачката.

За дедупликација претпочитајте документиран стабилен идентификатор на настанот кога е испорачан. Во спротивно, дефинирајте внимателно ограничен идентитет од релевантните полиња и тестирајте судири. Самиот број за следење не е идентитет на настан бидејќи една пратка може да создаде многу легитимни ажурирања.

Одделете ја историјата на настаните од тековната проекција на пратката. Чувањето историски скенирања не значи дека секое задоцнето скенирање треба да го пребрише прикажаниот статус. Ниту правилото „користи ја најновата временска ознака“ не е целосно: корекциите, тековите на враќање и различните значења на временските ознаки бараат експлицитна обработка.

Кај асинхрона обработка, потврдете само откако настанот ќе стигне до трајна точка на предавање, како потврден inbox-запис или трајна редица, според вашата архитектура. Следете ги документираните барања на давателот за потврда. HTTP ги дефинира семантиките на статусните кодови, но распоредот за повторување кај конкретниот испраќач мора да произлегува од неговиот сопствен договор.

Извршете контролирана проверка во живо и поставете критериуми за објавување

Откако ќе поминат детерминистичките тестови, регистрирајте овластена пратка преку вистинската интеграција и потврдете ја целосната патека. Проверете дали давателот го прифатил предвидениот запис, дали конфигурацијата на повратниот повик упатува кон точната околина и дали влезните податоци се мапираат кон очекуваната пратка.

Не барајте секој статус на пратката да се појави за време на проверката во живо. Реалните пратки не се контролирани фикстури. Користете го извршувањето во живо за потврдување на поврзаноста и забележаната компатибилност со договорот; користете фикстури што може да се репродуцираат за ретки или деструктивни сценарија.

Пред објавување, барајте ги следните резултати:

  • Документираните успешни одговори и одговори со грешки се обработуваат, вклучувајќи неуспеси на ниво на ставки ако API-то поддржува групни операции.
  • Истекот на времето не активира слепи повторувања на создавањето кога првото барање можеби веќе успеало.
  • Дупликатните настани не можат да создадат дупликатни деловни активности.
  • Невалидните повратни повици не можат да ја променат состојбата на пратката.
  • Неуспесите на worker-ите оставаат настани што може да се обноват наместо тивко да ги изгубат.
  • Развојниот сообраќај не може да известува реални клиенти или да ги менува продукциските нарачки.
  • Логовите ги поврзуваат барањата, примените настани, резултатите од обработката и обидите за известување без изложување тајни.

Објавувањето е подготвено кога можете да го објасните и нормалниот тек и начинот на кој системот се обновува по неизвесно барање, повторен повратен повик или прекинат worker. Едно успешно пребарување на следење не е доволно.

ЧПП

Можам ли да тестирам интеграција за следење без sandbox?

Да. Симулирајте ја границата на излезното API, репродуцирајте документирани фикстури за повратни повици и локално тестирајте ги нормализацијата и деловните правила. Потоа користете овластена пратка во живо за да ја потврдите вистинската поврзаност. Ова обезбедува значително покривање, но не го репродуцира недокументираното однесување на давателот.

Зошто моето барање за следење успева, но не враќа настани?

Прифаќањето на барањето и достапноста на податоците за следење се различни резултати. Проверете ги деталите во одговорот на давателот, барањата за регистрација, правилата за идентификација на превозникот и документираното однесување за пратки без настани. Не измислувајте информации за движење или достава за да пополните празна временска линија.

Дали успешен лажен webhook докажува дека ќе пристигнат вистински webhook-и?

Не. Тој ја докажува само патеката проверена од mock-тестот. Реалната испорака зависи и од конфигурацијата на давателот, јавната достапност, TLS, автентикацијата и вистинскиот договор за повратни повици. Потврдете ги со тестна испорака поддржана од давателот или со овластен тек во живо.

Дали треба да вратам HTTP 200 пред да заврши обработката?

Следете го документираниот договор на давателот за потврда. Кај асинхрон дизајн, потврдете по трајното прифаќање, а потоа обработете во worker. Враќањето успех пред трајното прифаќање може да изгуби настан ако процесот веднаш потоа откаже.

Како треба да ги тестирам известувањата до клиентите?

Испраќајте ги сите развојни известувања до контролиран систем за прием. Потврдете ја дестинацијата, шаблонот, преминот што го активира известувањето и бројот на испраќања. Репродуцирајте го истиот настан и симулирајте повторувања на worker-от за да потврдите дека едно ажурирање на пратката не создава повторени пораки до клиентите.

Извори

  • 17TRACK Tracking API — официјална почетна точка за производот Tracking API.
  • Документација за 17TRACK API — референца за договорот за интеграција специфичен за давателот; тука потврдете ги применливите барања за тестирање и повратни повици.
  • RFC 9110: HTTP Semantics — семантика на HTTP одговорите и аспекти за повторување на барањата.
  • RFC 2104: HMAC — стандардизираната конструкција за автентикација на пораки разгледана во упатствата за безбедност на повратните повици.