Тести й оновлення однією командою

Слова, якими користуватимемось

Що ти зробиш сьогодні

Теорія

1. Чому «я перевірив руками» перестає працювати

Твій сервіс уже вміє чимало: показує список, додає запис, відхиляє порожню назву, не дає сторонньому нічого видалити, повертає 404 на неіснуючий запис. Кожну з цих речей ти колись перевірив руками: відкрив сторінку, заповнив форму, натиснув кнопку, подивився результат.

Складність у тому, що перевіряти доводиться не один раз, а після кожної правки. Причому перевіряти треба не лише те, що ти щойно змінив. Ось як це виглядає насправді. Ти правиш один рядок у функції, яка готує список, і не помічаєш, що тепер вона повертає записи без поля id. Кнопка «видалити» бере id саме звідти — і видалення перестає працювати, хоча ти його не чіпав. У браузері ти дивишся тільки на список, бо список і правив. Помилку знаходить хтось інший через тиждень.

Повна ручна перевірка всіх п’яти дій займає хвилини три. Правок за заняття буває п’ятнадцять. Ніхто не робить п’ятнадцять разів по три хвилини — тому перевіряють лише змінене, і решта поступово ламається непомітно.

Тест

Функція, яка сама виконує дію в програмі й перевіряє, що результат саме такий, як очікується. Якщо результат інший — тест повідомляє про це і показує, чим фактичне значення відрізняється від очікуваного. Про такий тест кажуть «тест упав» або «тест не пройшов»; далі на сторінці це слово вживається саме в цьому значенні.

assert

Команда Python, що означає «далі має бути правда». Рядок assert 2 + 2 == 4 не робить нічого й виконання йде далі. Рядок assert 2 + 2 == 5 зупиняє функцію з помилкою AssertionError. Тести складаються переважно з таких рядків.

pytest

Програма, яка сама знаходить у вказаній теці всі файли з іменами виду test_*.py, запускає в них усі функції, чиї імена починаються з test_, і друкує підсумок: скільки функцій пройшло, скільки впало і на якому саме рядку. Запускати тести по одному руками не треба.

Порівняння з тим, що ти вже робив: коли вчитель перевіряє контрольну за ключем із відповідями, він не розв’язує задачу заново — звіряє твій результат із очікуваним. Рядок assert робить те саме, тільки за мілісекунди й без участі людини.

2. Як влаштований тест на pytest

Тести лежать в окремій теці tests усередині ~/app. Це звичайні файли Python, тільки з двома правилами іменування: файл має називатися test_щось.py, а функція всередині — починатися з test_. Функцію з іншим іменем pytest просто не запустить і навіть не поскаржиться.

Щоб перевірити ендпоінт, тесту треба надіслати HTTP-запит. Можна було б робити це через мережу, командою на кшталт curl, але тоді тест залежав би від того, чи запущена служба, чи вільний порт, чи працює nginx. FastAPI дає простіший інструмент.

Тестовий клієнт (TestClient)

Об’єкт, який приймає запит і передає його твоєму застосунку напряму, у тому самому процесі Python, а повертає ту саму відповідь, що прийшла б через мережу: код стану, тіло, заголовки. Служба для цього не потрібна — тести працюють навіть тоді, коли club-api зупинена.

Фікстура

Функція, яка готує щось потрібне для тесту й віддає це тестові. Наприклад, фікстура owner віддає тестовий клієнт, який уже має куку власника. Тесту не треба вводити логін і пароль — він одразу пише owner.post(...).

conftest.py

Файл, у якому лежать фікстури. pytest знаходить його сам і підставляє фікстури в усі тести з тієї самої теки. Імпортувати цей файл у тестах не треба, і саме тому його ім’я має бути записане точно так.

Щоб отримати фікстуру, тест згадує її ім’я серед своїх параметрів:

def test_list_returns_200(guest):
    response = guest.get("/api/habits")
    assert response.status_code == 200

Тут guest — не звичайний аргумент, який ти передаєш сам. Ти ніде не викликаєш test_list_returns_200(...): функцію викликає pytest. Він бачить у параметрах ім’я guest, знаходить фікстуру з таким іменем у conftest.py, виконує її і підставляє результат.

Сенс фікстур простий: підготовка перед тестами в усіх п’яти функціях однакова. Замість чотирьох однакових рядків у кожній із п’яти функцій ти пишеш їх один раз у conftest.py.

3. Тести не повинні псувати справжні дані

Тест, який додає запис, справді його додає. Якщо тести працюють з тією самою базою, що й сервіс, то після десяти запусків у твоєму списку буде десять записів «Тестовий запис», і на демо-дні їх побачать усі гості.

Є й друга причина, менш очевидна. Тест «запис додається» рахує записи до і після. Якщо база щоразу інша, результат тесту залежить від того, скільки разів ти вже його запускав. Тест, який сьогодні проходить, а завтра ні, без жодної зміни коду, нічого не показує: за його результатом не можна судити про код, тому такий тест швидко перестають запускати.

Тому перед запуском тестів файл бази копіюють у тимчасову теку, і тести працюють з копією. Справжня база при цьому не змінюється, а кожен запуск починається з однакового стану.

Технічно це один рядок. db.py бере шлях до файлу бази зі змінної DB_PATH. Файл conftest.py робить копію й записує в DB_PATH шлях до неї — до того, як буде виконано перший запит. Далі всі запити йдуть у копію, бо db.py дивиться на цю змінну щоразу, коли відкриває з’єднання. Писати цей код тобі не треба, він уже є в заготовці; треба розуміти, що він там робить.

4. Деплой: кроки, записані у файл

Деплой (викочування)

Перенести нову версію коду туди, де нею користуються, і зробити так, щоб працювала саме вона. У тебе це чотири дії: забрати коміти з ~/repo.git, запустити тести, перезапустити службу, переконатися, що сервіс відповідає.

git pull

Забирає нові коміти з віддаленого репозиторію й додає їх у твою робочу теку. Віддалений репозиторій у нашому курсі — це ~/repo.git, тека на цьому самому сервері, яку ти налаштував на занятті 03. Не GitHub.

Залежності

Сторонні бібліотеки, без яких проєкт не запуститься: fastapi, uvicorn, pyyaml, bcrypt. У нас вони стоять у спільному оточенні /opt/club/venv, однаковому для всієї групи, тому кроку встановлення в нашому deploy.sh не буде. У проєктах поза курсом такий крок зазвичай є: там оточення в кожного своє.

deploy.sh

Текстовий файл із командами, які виконуються згори вниз — так само, ніби ти набрав їх у терміналі одну за одною. Розширення .sh означає, що виконує їх bash, та сама програма, що приймає твої команди в SSH.

Зараз ти оновлюєш сервіс руками: чотири-п’ять команд, які треба пам’ятати в правильному порядку. За тиждень порядок забувається, а перед демо-днем його згадують поспіхом і пропускають крок. Тому кроки записують у файл один раз.

Три налаштування на початку скрипта

Перший змістовний рядок будь-якого скрипта, який щось міняє на сервері, виглядає так:

set -euo pipefail

Це три окремі налаштування, записані разом:

• -e — зупинити скрипт на першій команді, що завершилася з помилкою. Без цього скрипт спокійно перезапустив би службу навіть після падіння тестів: наступний рядок виконується незалежно від того, чим закінчився попередній.
• -u — вважати помилкою звертання до змінної, якій не присвоїли значення. Ловить одруківки в іменах: без нього $VNEV замість $VENV дасть порожній рядок, і команда виконається зовсім не так, як задумано.
• -o pipefail — якщо в ланцюжку перша | друга впала перша команда, увесь ланцюжок вважається невдалим. Без цього bash дивиться лише на останню команду ланцюжка.

Код виходу

Число, яке команда лишає після себе: 0 означає «виконано без помилок», будь-яке інше число — помилку. Подивитися код останньої команди можна так: echo $?. Саме за цим числом bash розуміє, впала команда чи ні. Коли хоч один тест падає, pytest повертає не 0 — і скрипт із set -e зупиняється саме на цьому рядку.

Порядок рядків у скрипті має значення. Перевірка, яка стоїть після дії, від цієї дії вже не убереже.

5. Двічі поспіль — той самий результат

Один із критеріїв заняття звучить так: deploy.sh двічі поспіль дає той самий результат. Це означає: запустив скрипт — він відпрацював до кінця; запустив ще раз одразу — він знову відпрацював до кінця без помилок, і стан сервера після другого запуску такий самий, як після першого.

Властивість «повторний запуск нічого не псує й лишає той самий стан» називають ідемпотентністю. Слово довге, ідея проста: команду можна виконати двічі, і другий раз нічого не змінить.

Різниця видна на двох прикладах. git pull, коли нових комітів немає, друкує Already up to date. і виходить з кодом 0 — стан не змінився. А рядок echo "готово" >> version.txt при кожному запуску дописує рядок у файл: після трьох запусків у файлі три рядки, і результат щоразу інший.

Ти стикаєшся з цією різницею щодня. Натиснути «зберегти» двічі — файл лишиться той самий. Натиснути «надіслати» двічі — у чаті буде два однакові повідомлення. Перша дія ідемпотентна, друга ні.

Наш скрипт ідемпотентний: git pull без нових комітів нічого не змінює, тести щоразу працюють з новою копією бази, перезапуск служби піднімає той самий код, перевірка тільки читає відповідь. Тому його можна запускати скільки завгодно разів поспіль.

Практика

У прикладах — таблиця habit і ендпоінти /api/habits із занять 04 і 05. Підставляй свої назви: вони записані у project.yaml у розділах database і endpoints.

ssh bohdan.g9@91.219.61.4
cd ~/app
git status --short
/opt/club/venv/bin/python -m pytest --version
/opt/club/venv/bin/python -c "import httpx; print('httpx на місці')"
grep -n "api/ping" ~/app/main.py
grep -n -- "--port" ~/.config/systemd/user/club-api.service

mkdir -p ~/app/tests
printf '__pycache__/\n*.pyc\n.pytest_cache/\n' > ~/app/.gitignore
cat ~/app/.gitignore
ls -a ~/app

nano ~/app/tests/conftest.py

"""Підготовка для тестів. Готова заготовка — цей файл не редагуємо.

Робить три речі:
  1) додає ~/app у список тек, де Python шукає модулі, щоб працював import main;
  2) підміняє базу на копію, щоб тести не змінювали справжніх даних;
  3) дає дві фікстури: guest — клієнт без входу, owner — клієнт із кукою власника.
"""
import shutil
import sys
import tempfile
from pathlib import Path

import pytest
import yaml
from fastapi.testclient import TestClient

APP_DIR = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(APP_DIR))

import db  # імпорт стоїть нижче за sys.path.insert навмисно

# --- копія бази -------------------------------------------------------
_tmp_db = Path(tempfile.mkdtemp(prefix="club-tests-")) / "test.db"
shutil.copy(db.DB_PATH, _tmp_db)
db.DB_PATH = _tmp_db          # з цієї миті всі запити йдуть у копію

import auth
from main import app

CFG = yaml.safe_load((APP_DIR / "project.yaml").read_text(encoding="utf-8"))


@pytest.fixture
def guest():
    """Клієнт без входу — так твій сервіс бачить стороння людина."""
    with TestClient(app) as client:
        yield client


@pytest.fixture
def owner():
    """Клієнт із кукою власника — пароль у тесті вводити не треба."""
    table = CFG["auth"]["table"]
    rows = db.query(f"SELECT login FROM {table} LIMIT 1")
    assert rows, "у таблиці власника немає жодного рядка, дивись заняття 07"
    with TestClient(app) as client:
        client.cookies.set(auth.COOKIE_NAME, auth.make_session(rows[0]["login"]))
        yield client

nano ~/app/tests/test_api.py

"""Тести API. Запуск із ~/app:
    /opt/club/venv/bin/python -m pytest -q tests
"""

LIST = "/api/habits"      # підстав свою адресу з project.yaml, розділ endpoints


def test_list_returns_200(guest):
    """Список відкривається без входу і повертає список записів."""
    response = guest.get(LIST)
    assert response.status_code == 200
    assert isinstance(response.json(), list)

cd ~/app
/opt/club/venv/bin/python -m pytest -q tests

.                                                     [100%]
1 passed in 0.42s

def test_owner_creates_item(owner):
    """Власник додає запис — він з'являється у списку."""
    before = len(owner.get(LIST).json())
    response = owner.post(LIST, json={"title": "Тестовий запис"})
    assert response.status_code in (200, 201)
    after = owner.get(LIST).json()
    assert len(after) == before + 1
    assert after[0]["title"] == "Тестовий запис"


def test_empty_title_rejected(owner):
    """Порожня назва — це помилка в даних, тобто 422, а не 500."""
    response = owner.post(LIST, json={"title": ""})
    assert response.status_code == 422


def test_guest_cannot_delete(guest, owner):
    """Сторонній не видаляє чужий запис."""
    owner.post(LIST, json={"title": "Не видаляти"})
    item_id = owner.get(LIST).json()[0]["id"]
    response = guest.delete(f"{LIST}/{item_id}")
    assert response.status_code == 401


def test_delete_missing_gives_404(owner):
    """Видалення неіснуючого запису — 404."""
    response = owner.delete(f"{LIST}/999999")
    assert response.status_code == 404

/opt/club/venv/bin/python -m pytest -q tests

.....                                                 [100%]
5 passed in 0.71s

nano ~/app/main.py

return query("SELECT * FROM habit ORDER BY id DESC LIMIT 1")

/opt/club/venv/bin/python -m pytest -q tests

.F...                                                 [100%]
=================================== FAILURES ===================================
___________________________ test_owner_creates_item ____________________________

    def test_owner_creates_item(owner):
        before = len(owner.get(LIST).json())
        response = owner.post(LIST, json={"title": "Тестовий запис"})
        assert response.status_code in (200, 201)
        after = owner.get(LIST).json()
>       assert len(after) == before + 1
E       assert 1 == 2

tests/test_api.py:21: AssertionError
1 failed, 4 passed in 0.68s

git checkout -- main.py
/opt/club/venv/bin/python -m pytest -q tests

cd ~/app
git add .gitignore tests
git status --short
git commit -m "тести: п’ять перевірок API"
git push origin master

nano ~/app/deploy.sh

#!/usr/bin/env bash
# Викочування нової версії. Заняття 09.
# Запуск:  ./deploy.sh
set -euo pipefail

VENV=/opt/club/venv
UNIT="$HOME/.config/systemd/user/club-api.service"
PORT=$(grep -oP '(?<=--port[ =])\d+' "$UNIT" || true)

if [ -z "$PORT" ]; then
    echo "ПОМИЛКА: у $UNIT немає рядка з --port"
    exit 1
fi

cd "$(dirname "$0")"

echo "==> 1/4 забираємо коміти з ~/repo.git"
git pull --ff-only origin master

echo "==> 2/4 тести"
"$VENV/bin/python" -m pytest -q tests

echo "==> 3/4 перезапуск служби"
systemctl --user restart club-api || {
    echo "ПОМИЛКА: служба не перезапустилася"
    echo "Дивись:  journalctl --user -u club-api -n 30"
    exit 1
}
sleep 2

echo "==> 4/4 перевірка, що сервіс відповідає"
code=$(curl -s -o /dev/null -w "%{http_code}" "http://127.0.0.1:$PORT/api/ping" || true)
if [ "$code" = "200" ]; then
    echo "ГОТОВО: /api/ping відповів 200"
else
    echo "ПОМИЛКА: /api/ping відповів $code"
    echo "Дивись:  journalctl --user -u club-api -n 30"
    exit 1
fi

chmod +x ~/app/deploy.sh
cd ~/app
./deploy.sh

==> 1/4 забираємо коміти з ~/repo.git
From /home/bohdan.g9/repo
 * branch            master     -> FETCH_HEAD
Already up to date.
==> 2/4 тести
.....                                                 [100%]
5 passed in 0.71s
==> 3/4 перезапуск служби
==> 4/4 перевірка, що сервіс відповідає
ГОТОВО: /api/ping відповів 200

./deploy.sh
echo $?

nano ~/app/main.py

./deploy.sh
echo $?

==> 1/4 забираємо коміти з ~/repo.git
From /home/bohdan.g9/repo
 * branch            master     -> FETCH_HEAD
Already up to date.
==> 2/4 тести
.F...                                                 [100%]
...
1 failed, 4 passed in 0.66s
1

curl -s http://127.0.0.1/u/bohdan.g9/api/ping
curl -s http://127.0.0.1/u/bohdan.g9/api/habits

git checkout -- main.py
./deploy.sh

cd ~/app
git add deploy.sh tests
git status --short
git commit -m "деплой: тести перед перезапуском, перевірка ping після"
git push origin master
git -C ~/repo.git log --oneline -1

Що перевіряє чекер

Три критерії заняття 09, усі три перевіряє чекер. Він запускається за розкладом, тому відмітка в кабінеті з’являється не в ту саму секунду, коли ти виконав команду. Команди чекер виконує в тебе в ~/app ті самі, що й ти на практиці, тому все, що він побачить, ти можеш побачити сам заздалегідь.

Домашнє завдання

git add tests
git commit -m "тест: довга назва має давати 422 (поки падає)"
# правиш main.py, домагаєшся 6 passed
git add main.py
git commit -m "перевірка довжини назви в моделі NewItem"
git push origin master

cd ~/app
./deploy.sh
echo $?

Якщо щось не працює

ModuleNotFoundError: No module named 'main'

pytest не бачить твого застосунку. Перевір дві речі: файл лежить там, де треба, і команда запускається з правильної теки.

ls ~/app/tests/conftest.py
cd ~/app
/opt/club/venv/bin/python -m pytest -q tests

Якщо ls відповів No such file or directory, файл із фікстурами опинився не в tests/ — перенеси його. Запускай саме python -m pytest: варіант без -m не додає поточну теку в шлях пошуку модулів, і імпорти працюють по-різному залежно від того, звідки ти запустив команду.

fixture 'owner' not found

Три причини, у порядку частоти. Перша: файл із фікстурами названо інакше — ім’я має бути точно conftest.py, це не довільна назва, pytest шукає саме її. Друга: у самому conftest.py сталася помилка, і pytest не зміг його виконати; тоді вище, у блоці ERRORS, буде видно справжню причину — читай її, а не рядок про фікстуру. Третя: одруківка в імені параметра — ownre замість owner.

Найчастіша помилка всередині conftest.py — KeyError: 'table'. Вона означає, що в project.yaml у розділі auth немає самого поля table. Якщо поле є, але порожнє, помилка буде інша: у запит підставиться None, і SQLite поскаржиться на неправильний запит. В обох випадках впиши в це поле назву своєї таблиці власника із заняття 07.

Тест на порожню назву дає 500 замість 422

500 означає, що код упав сам, не встигши нічого відповісти. 422 віддає FastAPI, коли дані не пройшли перевірку моделі — тобто коли в моделі стоїть обмеження, наприклад title: str = Field(min_length=1). Якщо ж перевірка написана руками, рядком на кшталт if not title: raise Exception(...), вийде саме 500.

Подивись, як описана модель NewItem у main.py, і порівняй із заняттям 05. Після правки перезапускати службу для тестів не треба — тестовий клієнт бере код напряму з файлу.

./deploy.sh: Permission denied або command not found

Перше — файлу не поставили ознаку «можна запускати»: chmod +x ~/app/deploy.sh. Друге — ти набрав deploy.sh без ./, і bash шукав таку команду серед системних програм.

Окремий випадок — повідомлення bad interpreter: /usr/bin/env bash^M. ^M — це другий символ кінця рядка: у Windows кінець рядка позначається двома символами, а в Linux одним. У файл він потрапляє, якщо текст скрипта набирали в Windows-редакторі й перенесли на сервер разом із цими символами. Якщо ти створював deploy.sh через nano прямо на сервері, такого не станеться. Прибрати їх:

sed -i 's/\r$//' ~/app/deploy.sh
./deploy.sh

git pull: Your local changes would be overwritten by merge

У ~/app є правки, яких немає в жодному коміті, і git не хоче їх затерти комітами, що приходять. Подивись, що це за файли:

git status --short

Далі одне з двох. Якщо правки потрібні — закомить їх:

git add -A
git commit -m "опис того, що змінив"
./deploy.sh

Якщо це залишки експериментів — відклади їх убік:

git stash
./deploy.sh

git stash прибирає незакомічені зміни в окреме сховище, і робоча тека стає чистою. Повернути їх потім можна командою git stash pop, а подивитися список відкладеного — git stash list.