Kuinka testata RESTful API:ta FastAPI:lla

RESTful API:n testaaminen on tärkeä osa ohjelmistokehityksen prosessia, ja se varmistaa, että sovelluksesi toimii odotetulla tavalla. FastAPI tarjoaa erinomaisia työkaluja testaukseen, kuten TestClient-luokan, jonka avulla voidaan testata API:n loppupisteitä ilman, että palvelinta tarvitsee käynnistää. Tässä osassa käymme läpi, kuinka määritellä testit ja testausympäristö Pytestillä, ja kuinka käyttää FastAPI:n tarjoamia testausominaisuuksia.

Testauksen valmistelu alkaa luomalla conftest.py-moduuli, jossa määritellään testitietokanta ja testitehtävien tiedot. Määrittelemme ensin testitiedoston nimen ja luettelon testitehtävistä:

python
Copy code
TEST_DATABASE_FILE = "test_tasks.csv"

TEST_TASKS_CSV = [
    {"id": "1", "title": "Test Task One", "description": "Test Description One", "status": "Incomplete"},
    {"id": "2", "title": "Test Task Two", "description": "Test Description Two", "status": "Ongoing"},
]

Tässä esimerkissä testitehtäville määritellään ID, otsikko, kuvaus ja tila. Näistä tiedoista luodaan sitten Pythonin listasta sanakirjoja, joissa tehtävien ID:t muutetaan kokonaisluvuiksi:

python
Copy code
TEST_TASKS = [
    {**task_json, "id": int(task_json["id"])}
    for task_json in TEST_TASKS_CSV
]

Tämän jälkeen voimme määritellä pytest-fixturen, joka valmistaa testitietokannan ennen jokaista testin suorittamista:

python
Copy code
import csv

import os
from pathlib import Path
from unittest.mock import patch
import pytest
@pytest.fixture(autouse=True)
def create_test_database():
    database_file_location = str(Path(__file__).parent / TEST_DATABASE_FILE)
    with patch("operations.DATABASE_FILENAME", database_file_location) as csv_test:
        with open(database_file_location, mode="w", newline="") as csvfile:

            writer = csv.DictWriter(csvfile, fieldnames=["id", "title", "description", "status"])

            writer.writeheader()
            writer.writerows(TEST_TASKS_CSV)
        yield csv_test
        os.remove(database_file_location)

Tämä fixture-testi luo tiedoston ja kirjoittaa siihen testitehtävät ennen jokaista testiajoa. patch-komento huolehtii siitä, että oikea tietokantatiedosto käytetään testauksen aikana. Testin suorittamisen jälkeen tiedosto poistetaan automaattisesti.

Kun fixtuuri on määritelty, kaikki testit moduulissa voivat hyödyntää tätä järjestelyä ilman erillistä määrittelyä. Testit kirjoitetaan seuraavaksi käyttäen FastAPI:n TestClient-luokkaa, joka mahdollistaa API-loppupisteiden testaamisen ilman palvelimen käynnistämistä.

Ensimmäinen testattava päätepiste on GET /tasks, joka palauttaa kaikki tietokannan tehtävät:

python
Copy code
from conftest import TEST_TASKS

def test_endpoint_read_all_tasks():
    response = client.get("/tasks")
    assert response.status_code == 200
    assert response.json() == TEST_TASKS

Tässä testissä varmistetaan, että API palauttaa kaikki tehtävät ja että HTTP-vastauskoodi on 200. Testissä tarkistetaan myös, että palautettu JSON vastaa määriteltyjä testitehtäviä.

Toinen testattava päätepiste on GET /tasks/{task_id}, joka palauttaa yksittäisen tehtävän ID:n perusteella:

python
Copy code
def test_endpoint_get_task():
    response = client.get("/task/1")
    assert response.status_code == 200
    assert response.json() == TEST_TASKS[0]
    response = client.get("/task/5")
    assert response.status_code == 404

Tässä testissä tarkistetaan, että olemassa oleva tehtävä palauttaa oikeat tiedot ja että ei-olemassa oleva tehtävä palauttaa virhekoodin 404.

Seuraavaksi testataan POST /task, joka lisää uuden tehtävän tietokantaan:

python
Copy code
from operations import read_all_tasks

def test_endpoint_create_task():
    task = {
        "title": "To Define",
        "description": "will be done",
        "status": "Ready",
    }
    response = client.post("/task", json=task)
    assert response.status_code == 200
    assert response.json() == {**task, "id": 3}
    assert len(read_all_tasks()) == 3

Testissä varmistetaan, että uusi tehtävä lisätään oikein tietokantaan ja että sen ID määritellään oikein.

Seuraavaksi testataan PUT /tasks/{task_id}, joka muokkaa olemassa olevaa tehtävää:

python
Copy code
def test_endpoint_modify_task():
    updated_fields = {"status": "Finished"}
    response = client.put("/task/2", json=updated_fields)
    assert response.status_code == 200
    assert response.json() == {**TEST_TASKS[1], **updated_fields}
    response = client.put("/task/3", json=updated_fields)
    assert response.status_code == 404

Tässä testissä tarkistetaan, että tehtävän tila päivittyy oikein ja että virheellinen tehtävän ID palauttaa virhekoodin 404.

Viimeinen testattava päätepiste on DELETE /tasks/{task_id}, joka poistaa tehtävän tietokannasta:

python
Copy code
def test_endpoint_delete_task():

    response = client.delete("/task/2")
    assert response.status_code == 200
    expected_response = TEST_TASKS[1]
    del expected_response["id"]
    assert response.json() == expected_response
    assert read_task(2) is None

Tässä testissä tarkistetaan, että poistettu tehtävä ei ole enää tietokannassa.

Kun kaikki testit on kirjoitettu, voidaan ne suorittaa Pytestillä:

bash
Copy code
$ pytest .

Jos kaikki testit menevät läpi, konsolissa näkyy viesti, joka ilmoittaa täydellisesti suoritettuista testeistä.

python
Copy code
@app.get("/tasks", response_model=list[TaskWithID])
def get_tasks(status: Optional[str] = None, title: Optional[str] = None):
    tasks = read_all_tasks()
    if status:
        tasks = [task for task in tasks if task.status == status]
    if title:
        tasks = [task for task in tasks if task.title == title]
    return tasks

Lisäksi voidaan lisätä hakutoiminto, joka mahdollistaa tehtävien etsimisen tietyllä hakusanalla otsikosta tai kuvauksesta:

python
Copy code
@app.get("/tasks/search", response_model=list[TaskWithID])

def search_tasks(keyword: str):
    tasks = read_all_tasks()
    filtered_tasks = [task for task in tasks if keyword.lower() in (task.title + task.description).lower()]
    return filtered_tasks

Tämä mahdollistaa käyttäjien etsiä tehtäviä, joissa hakusana esiintyy joko otsikossa tai kuvauksessa. Näin voidaan tehdä API:sta entistä joustavampi ja käyttäjäystävällisempi.

Miten testata ja debugata FastAPI-sovelluksia tehokkaasti?

Testikoodissa käytetään asynkronisia testejä hyödyntäen FastAPI:n ja httpx-kirjaston mahdollistamia työkaluja. Esimerkiksi AsyncClient yhdistettynä ASGITransport-kuljetukseen antaa mahdollisuuden testata FastAPI-sovellusta täysin asynkronisesti, mikä vastaa tuotantoympäristön toimintaa. Tällainen lähestymistapa varmistaa, että endpointit vastaavat odotetusti ja palauttavat oikeat statuskoodit ja vastaukset. Testien kerääminen komennolla pytest --collect-only auttaa varmistamaan, että testit löytyvät oikein.

Toisessa vaiheessa voidaan käyttää FastAPI:n omaa TestClient-luokkaa yksikkötestien kirjoittamiseen, joka on synkroninen ja siten usein yksinkertaisempi ja nopeampi kirjoittaa kuin asynkroninen versio. TestClient mahdollistaa HTTP-pyyntöjen simuloinnin suoraan sovellukselle, mikä tekee yksikkötestien kirjoittamisesta helppoa ja suoraviivaista. Yhteisten testikomponenttien, kuten testiclientin, jakaminen useiden testien kesken voidaan järjestää conftest.py-tiedoston avulla, joka on pytestin konventio testitiedostojen yhteisille fikstuureille.

Integraatiotestauksessa tarkastellaan sovelluksen eri komponenttien yhteistoimintaa. Erityisesti, kun sovellus käyttää ulkoisia palveluita tai tietokantoja, integraatiotestit ovat olennaisia. Esimerkiksi SQL-tietokantaan lisättävien ja sieltä luettavien tietueiden testaaminen varmistaa, että sovelluksen tietokantakerros toimii odotetusti. Tietokantayhteyden asettaminen sisältää ORM:n (Object Relational Mapper) konfiguroinnin, kuten SQLAlchemy:n Base-luokan määrittelyn, taulujen mallintamisen luokiksi ja moottorin (engine) luomisen, joka huolehtii yhteyksistä tietokantaan. Lisäksi on tärkeää konfiguroida sessioita hallitseva SessionLocal-luokka, joka mahdollistaa turvallisen ja hallitun istunnon avaamisen ja sulkemisen testien aikana.

Testausympäristön huolellinen rakentaminen, testausfiksuurien käyttö ja erilaisten testausmenetelmien hyödyntäminen parantavat sovelluksen laatua ja ylläpidettävyyttä merkittävästi. On huomioitava, että testaus ei ole vain virheiden löytämistä, vaan myös dokumentointia ja varmuuden luomista sovelluksen toimintakyvystä muutoksista huolimatta.

On tärkeää ymmärtää, että testausprosessin aikana testejä tulee pitää yllä ja päivittää sovelluksen kehittyessä. Lisäksi integraatiotestit vaativat usein erillisen testitietokannan tai transaktioiden hallinnan, jotta testien ajaminen ei vaikuta tuotantotietokantaan. Hyvä testauskäytäntö sisältää myös virheiden ja poikkeusten testaamisen, suorituskyvyn arvioinnin sekä jatkuvan integraation (CI) osana kehitysputkea. Näin varmistetaan, että sovellus kestää käyttökuormaa ja reagoi virhetilanteisiin hallitusti.

Miten luoda ja käyttää FastAPI-reitittimiä ja päätepisteitä?

FastAPI:n käyttöönotto tuo eteen monia etuja, kuten nopean kehityksen ja automaattisen dokumentaation. Yksi sen tärkeimmistä ominaisuuksista on kyky organisoida koodia reitittimien ja päätepisteiden avulla. Tämä lähestymistapa tekee koodista selkeämpää ja helpommin ylläpidettävää. Päätepisteet, jotka määrittelevät, miten HTTP-pyynnöt käsitellään, ovat keskeinen osa FastAPI-sovellusten rakennetta. Tässä käsitellään, miten päätepisteitä ja reitittimiä voi luoda ja käyttää FastAPI:ssa, sekä miten ne tekevät sovelluksesta tehokkaan ja modulaarisen.

python
Copy code
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def read_root():
    return {"Hello": "World"}

Tässä esimerkissä @app.get("/") määrittelee päätepisteen, joka vastaa GET-pyyntöihin "/"-osoitteessa. Tämä on yksinkertainen tapa luoda ensimmäinen API-päätepiste, joka palauttaa JSON-vastauksen.

Reitittimet: modulaarisuus ja ylläpidettävyys

Kun sovelluksessa on useita päätepisteitä, jotka sijaitsevat eri tiedostoissa, on suositeltavaa käyttää reitittimiä. Reitittimet mahdollistavat päätepisteiden ryhmittelyn eri moduuleihin, mikä parantaa koodin luettavuutta ja ylläpidettävyyttä. Tämä on erityisen hyödyllistä suurissa sovelluksissa, joissa on monia API-toimintoja. Esimerkiksi voimme luoda yhden reitittimen käyttäjien käsittelemiseen ja toisen reitittimen tuotteiden käsittelemiseen.

Reitittimen luominen tapahtuu seuraavasti. Ensiksi luodaan uusi tiedosto (esim. router_example.py), joka sisältää reitittimen määrittelyn:

python
Copy code
from fastapi import APIRouter

router = APIRouter()
@router.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Tässä esimerkissä reititin käsittelee GET-pyyntöjä, jotka liittyvät tuotteiden ID:hin. Tämä reititin voidaan liittää pääsovellukseen seuraavasti:

python
Copy code
import router_example

from fastapi import FastAPI
app = FastAPI()
app.include_router(router_example.router)
@app.get("/")
async def read_root():
    return {"Hello": "World"}

Reitittimen käyttö yksinkertaistaa koodin hallintaa ja antaa mahdollisuuden jakaa sovelluksen eri osat erillisiin tiedostoihin, mikä tekee kehityksestä entistä joustavampaa.

Uvicorn: palvelimen käynnistäminen

Kun sovellus on kirjoitettu, se täytyy käynnistää. FastAPI-sovelluksen käynnistämiseksi käytetään Uvicorn-palvelinta, joka on erittäin nopea ASGI-palvelin. Voit käynnistää palvelimen seuraavasti:

bash
Copy code
$ uvicorn main:app --reload

Automaattinen dokumentaatio: Swagger UI ja Redoc

Yksi FastAPI:n huippuominaisuuksista on sen kyky luoda automaattista dokumentaatiota. FastAPI luo automaattisesti kaksi dokumentaatiotyökalua, jotka helpottavat API:n testaamista ja tutkimista. Näitä ovat Swagger UI ja Redoc. Molemmat ovat interaktiivisia käyttöliittymiä, joiden avulla voit testata API-päätepisteitä suoraan selaimessa.

Postman: vaihtoehto Swagger UI:lle

Vaikka Swagger UI on helppokäyttöinen ja kätevä, monimutkaisemmissa testauksissa voi olla tarpeen käyttää toista työkalua, kuten Postmania. Postman on API-asiakas, joka tarjoaa laajat mahdollisuudet API-pyyntöjen rakentamiseen, testaamiseen ja dokumentointiin. Se on erityisen hyödyllinen monimutkaisissa testeissä ja suurissa projekteissa, joissa on useita päätepisteitä. Voit ladata Postmanin Postmanin viralliselta verkkosivustolta ja kokeilla sitä API-pyyntöjen tekemiseen FastAPI-sovellukseen.

Polku- ja kyselyparametrit

API-kehityksessä on tärkeää ymmärtää parametrien käsittely. Parametrit tekevät API:sta dynaamisemman ja joustavamman, sillä ne mahdollistavat käyttäjien syötteen vastaanottamisen ja käsittelemisen. FastAPI tukee monenlaisia parametreja, kuten polkuparametreja ja kyselyparametreja. Polkuparametrit ovat URL-osoitteen osia, jotka voivat muuttua pyyntöjen mukaan. Esimerkiksi "/books/{book_id}"-päätepisteessä {book_id} on polkuparametri.

Tässä esimerkissä luodaan API-päätepiste, joka hakee kirjan tiedot sen ID:n perusteella:

python
Copy code
@app.get("/books/{book_id}")

async def read_book(book_id: int):

    return {
        "book_id": book_id,
        "title": "The Great Gatsby",
        "author": "F. Scott Fitzgerald"
    }

Tässä käytetään polkuparametria book_id, joka on määritetty URL-osoitteessa. FastAPI hoitaa automaattisesti sen, että tämä parametri välitetään oikeassa muodossa funktioon. Jos käyttäjä syöttää ei-numeron, FastAPI antaa virheilmoituksen.

On myös tärkeää huomioida, että FastAPI tarjoaa automaattisen validoinnin tyypintarkistuksen avulla, joka takaa, että API:lle lähetetyt tiedot ovat oikeassa muodossa ja sääntöjen mukaisia.

Tärkeitä lisähuomioita

FastAPI:n avulla API-päätepisteet voidaan määritellä nopeasti ja tehokkaasti, mutta myös niiden testaaminen ja dokumentointi on olennaista sovelluksen kehitykselle. Automaattinen dokumentaatio, kuten Swagger UI ja Redoc, auttaa kehittäjää nopeasti tutustumaan luotuihin päätepisteisiin ja varmistamaan, että ne toimivat oikein. Käyttäjän ja kehittäjän välinen vuorovaikutus helpottuu, kun parametreja voidaan käyttää dynaamisesti, ja FastAPI tarjoaa välineet virheiden käsittelyyn ja tyypintarkistukseen, jotka parantavat sovelluksen luotettavuutta.