API do testów automatycznych

Testy automatyczne zatrzymują się zwykle w tym samym miejscu: aplikacja wysyła wiadomość potwierdzającą, a test nie ma jak jej odebrać. To API rozwiązuje problem w trzech wywołaniach — utwórz skrzynkę, poczekaj, odczytaj wiadomość.

Potrzebujesz do tego klucza dostępu. Dostaniesz go tutaj, bezpłatnie i bez zakładania konta: podaj adres e-mail, odbierz klucz, gotowe.

Odbierz klucz dostępu

Bezpłatnie i od razu. Potrzebujemy tylko adresu e-mail — na wypadek, gdybyśmy musieli skontaktować się w sprawie nadużyć, i żeby było wiadomo, do kogo należy klucz.

Szybki start

Trzy wywołania i tyle. Klucz dołączasz do każdego z nich.

# Der Schluessel gehoert in jeden Aufruf.
export GETSEND_KEY="gs_..."

# 1. Postfach anlegen
curl -s -X POST https://www.getsend.xyz/api/v1/inboxes \
     -H "Authorization: Bearer $GETSEND_KEY"

# {
#   "address": "a7k2m9x4p1q8w3z6@getsend.xyz",
#   "messages_url": "https://www.getsend.xyz/api/v1/inboxes/a7k2m9x4p1q8w3z6/messages"
# }

# 2. Postfach abfragen
curl -s -H "Authorization: Bearer $GETSEND_KEY" \
     https://www.getsend.xyz/api/v1/inboxes/a7k2m9x4p1q8w3z6/messages

# 3. Nachricht mit Inhalt lesen
curl -s -H "Authorization: Bearer $GETSEND_KEY" \
     https://www.getsend.xyz/api/v1/inboxes/a7k2m9x4p1q8w3z6/messages/193

Punkty końcowe

W narzędziach testowych

Cypress

// cypress/support/getsend.js
const API = 'https://www.getsend.xyz/api/v1'
const KEY = Cypress.env('GETSEND_KEY')   // nie im Quelltext ablegen
const kopf = { Authorization: `Bearer ${KEY}` }

Cypress.Commands.add('neuesPostfach', () =>
  cy.request({ method: 'POST', url: `${API}/inboxes`, headers: kopf }).its('body'))

// Wartet, bis eine Nachricht da ist -- Mail braucht ein paar Sekunden.
Cypress.Commands.add('warteAufMail', (box, versuche = 20) => {
  const lokal = box.address.split('@')[0]
  const holen = (rest) =>
    cy.request({ url: `${API}/inboxes/${lokal}/messages`, headers: kopf })
      .then((r) => {
        if (r.body.count > 0) return r.body.messages[0]
        if (rest <= 1) throw new Error('Keine Mail eingetroffen')
        return cy.wait(3000).then(() => holen(rest - 1))
      })
  return holen(versuche)
})

// Im Test:
it('bestaetigt die Registrierung', () => {
  cy.neuesPostfach().then((box) => {
    cy.visit('/registrierung')
    cy.get('#email').type(box.address)
    cy.get('form').submit()

    cy.warteAufMail(box).then((m) => {
      const lokal = box.address.split('@')[0]
      cy.request({ url: `${API}/inboxes/${lokal}/messages/${m.id}`, headers: kopf })
        .then((r) => {
          const link = r.body.text.match(/https?:\/\/\S+/)[0]
          cy.visit(link)
          cy.contains('Konto bestaetigt')
        })
    })
  })
})

Python / Selenium

# Selenium, pytest oder jedes andere Werkzeug -- die Schnittstelle
# ist ein gewoehnlicher HTTP-Aufruf.
import os, re, time, requests

API  = "https://www.getsend.xyz/api/v1"
KOPF = {"Authorization": "Bearer " + os.environ["GETSEND_KEY"]}

def neues_postfach():
    return requests.post(f"{API}/inboxes", headers=KOPF, timeout=10).json()

def warte_auf_mail(box, versuche=20, pause=3):
    lokal = box["address"].split("@")[0]
    for _ in range(versuche):
        r = requests.get(f"{API}/inboxes/{lokal}/messages", headers=KOPF, timeout=10).json()
        if r["count"]:
            mid = r["messages"][0]["id"]
            return requests.get(f"{API}/inboxes/{lokal}/messages/{mid}",
                                headers=KOPF, timeout=10).json()
        time.sleep(pause)
    raise AssertionError("Keine Mail eingetroffen")

box = neues_postfach()
driver.find_element(By.ID, "email").send_keys(box["address"])
driver.find_element(By.CSS_SELECTOR, "form").submit()

mail = warte_auf_mail(box)
link = re.search(r"https?://\S+", mail["text"]).group(0)
driver.get(link)

Ograniczenia

Wiadomości są usuwane po siedmiu dniach. Na jeden klucz przypada 60 nowych skrzynek i 3000 zapytań na godzinę; powyżej tego API odpowiada kodem 429 i nagłówkiem Retry-After.

Serwis przyjmuje pocztę wyłącznie dla domeny getsend.xyz. Nie ma własnych domen.

To niewielki serwis na jednym serwerze. Do testów w trakcie prac programistycznych wystarczy; nie jest pomyślany jako element aplikacji produkcyjnej i nie obiecujemy dostępności.

Co daje klucz, a czego nie daje

Skrzynka utworzona przez API należy do Twojego klucza. Inny klucz jej nie odczyta, nawet jeśli zna adres.

W interfejsie webowym jest inaczej: getSend od zawsze pokazuje każdą skrzynkę, której adres się wpisze. Kto zna Twój adres, zobaczy wiadomości w przeglądarce mimo wszystko. Dlatego tworzone adresy mają 16 znaków i praktycznie nie da się ich zgadnąć — i dlatego do tych skrzynek nie należy wysyłać niczego poufnego.

Traktuj klucz jak hasło. Jego miejsce jest w zmiennej środowiskowej, a nie w kodzie źródłowym ani w publicznym repozytorium.