Testing Guide

🚀 Quickstart לטסטים

  1. הגדרת משתני סביבה (בזמן הרצה):

export DISABLE_ACTIVITY_REPORTER=1
export DISABLE_DB=1
export BOT_TOKEN=x
export MONGODB_URL='mongodb://localhost:27017/test'
  1. התקנת תלויות טסטים וכיסוי:

pip install -U pytest pytest-asyncio pytest-cov
  1. הרצות שימושיות:

# כל הטסטים במצב שקט
pytest -q

# בדיקת קובץ/טסט ספציפי
pytest tests/test_bot_handlers_show_command_more.py::test_show_command_renders_html_and_escapes_code_and_buttons_id -q

הנחיות קריטיות

  • כל IO בטסטים יתבצע תחת tmp_path בלבד.

  • מחיקות יתבצעו רק תחת /tmp באמצעות wrapper בטוח.

  • מבודדים את תלות python-telegram-bot באמצעות Stubs כדי להימנע מקריאות אמתיות.

טעינת Stubs לטלגרם

כדי להריץ טסטים ללא python-telegram-bot, קיימים stubs ב-tests/_telegram_stubs.py והם נטענים אוטומטית דרך tests/conftest.py:

# tests/conftest.py
import os
os.environ.setdefault('DISABLE_ACTIVITY_REPORTER', '1')
os.environ.setdefault('DISABLE_DB', '1')
os.environ.setdefault('BOT_TOKEN', 'x')
os.environ.setdefault('MONGODB_URL', 'mongodb://localhost:27017/test')
import tests._telegram_stubs  # noqa

דוגמת שימוש ב‑tmp_path

def test_file_operations(tmp_path):
    test_file = tmp_path / "test.py"
    test_file.write_text("print('hello')")
    assert test_file.exists()

מחיקה בטוחה

from pathlib import Path
import shutil

def safe_rmtree(path: Path, allow_under: Path) -> None:
    p = path.resolve()
    base = allow_under.resolve()
    if not (p == base or base in p.parents) or p in (Path('/'), base.parent, Path.cwd()):
        raise RuntimeError(f"Refusing to delete unsafe path: {p}")
    shutil.rmtree(p)

Mocking HTTP ב‑github_menu_handler

בגלל שינוי התשתית ל‑HTTP במודול github_menu_handler הוגדר שכבת shim יציבה לטסטים:

  • gh.requests.get – ממשק GET שניתן לבצע עליו monkeypatch בקלות.

  • gh.http_request – שכבת עטיפה לכל הבקשות; ב‑GET היא קוראת ל‑gh.requests.get וב‑non‑GET קוראת ישירות ל‑gh._http_sync_request.

הנחיות מעשיות:

  • עבור הורדות/GET (למשל zipball): עדיף לבצע monkeypatch על gh.requests.get במקום על requests.get הגלובלי.

  • עבור קריאות non‑GET (POST/PUT/DELETE): בצעו monkeypatch על gh._http_sync_request.

  • אין יציאה לרשת בזמן טסטים – תמיד למקבש (monkeypatch) את הקריאות.

דוגמה – Mock ל‑GET דרך ה‑shim:

import github_menu_handler as gh

def test_zip_download(monkeypatch):
    class _Resp:
        headers = {"Content-Length": "10"}
        def raise_for_status(self):
            pass
        def iter_content(self, chunk_size=131072):
            yield b"1234567890"

    def fake_get(url, **kwargs):
        return _Resp()

    monkeypatch.setattr(gh.requests, "get", fake_get)
    # המשך הקריאה לפונקציה שבפועל מבצעת את ההורדה…

דוגמה – Mock ל‑non‑GET דרך _http_sync_request:

import github_menu_handler as gh

def test_non_get(monkeypatch):
    sentinel = object()

    def fake_req(method, url, **kw):
        assert method == "POST"
        return sentinel

    monkeypatch.setattr(gh, "_http_sync_request", fake_req)
    assert gh.http_request("POST", "https://example.com", data=b"x") is sentinel

השהיות של קוד הייצור בטסטים

קוד הייצור ממתין בכוונה, והטסטים לא ממתינים איתו. ה-rate limit בין קריאות ל-GitHub (apply_rate_limit_delay ב-github_menu_handler.py), ה-retry עם backoff (resilience.py, http_sync.py) ותקרת ההמתנה לתשובה ב-http_async.py ממתינים באמת, וטסט שעובר בהם ממתין ועובר בלי שאיש יראה. לכן tests/conftest.py קובע להם ערכי בדיקה פעם אחת, בבלוק משתני הסביבה שלו. הוא קובע אותם בהשמה ולא ב-setdefault, ולכן הם חלים על כל הרצה — ci.yml, deploy.yml והרצה מקומית — גם כשהמעטפת מייצאת ערך אחר, ומאותה סיבה הם לא נקבעים ב-env של workflow.

  • טסט שהנושא שלו הוא ההשהיה עצמה קובע אותה בעצמו ב-monkeypatch.setenv, ולא נשען על ברירת המחדל של הייצור או של tests/conftest.py. כך עושים tests/test_github_menu_backoff_delay.py ו-tests/test_http_sync_adapter_retries.py.

  • השהיה חדשה בקוד הייצור מקבלת ערך בדיקה באותו בלוק, באותו PR. לא מנטרלים אותה בקובץ הטסטים שבמקרה שם לב אליה, כי הקובץ הבא לא יידע על כך.

  • המתנה אמיתית גם מסתירה באגים, ולא רק עולה זמן. טסט שבודק התנהגות ”באותה שנייה“ לא מגיע אליה כשכל קריאה ממתינה. test_backup_id_is_unique_within_the_same_second עבר גם כשההגנה שהוא בודק הוסרה, כל עוד ההשהיה רצה.

רישום Blueprint בסביבת טסטים

במהלך הרצת בדיקות (pytest), האפליקציה מבטיחה שרישום ה‑Blueprint של collections_api יבוצע תמיד — גם אם הייבוא נכשל או אם הקובץ config חסר.

מה קורה בפועל:

  • אם המודול נטען בהצלחה: ה‑Blueprint נרשם כרגיל תחת /api/collections באמצעות collections_bp (או bp).

  • אם הייבוא נכשל או אין bp: נרשם Blueprint דיאגנוסטי שמונע שגיאות 404 ומחזיר JSON עם סטטוס 503, למשל:

    {"ok": false, "error": "collections_api_unavailable", "diagnostic": true}
    
  • בפרודקשן: ההתנהגות לא משתנה — חריגים נרשמים ללוג בלבד, ואין Blueprint דמה.

דוגמה לקוד שמבטיח רישום בסביבת pytest (חלק מ‑webapp/app.py):

import os, sys
_is_pytest = (
    bool(os.getenv("PYTEST_CURRENT_TEST"))
    or ("pytest" in sys.modules)
    or os.getenv("PYTEST") == "1"
    or os.getenv("PYTEST_RUNNING") == "1"
)
if _is_pytest:
    enabled = True  # הפיצ'ר נכפה ל-True בזמן טסטים

בדיקות מול מונגו אמיתי

רוב הבדיקות בריפו רצות מול stub בפייתון טהור, וזה נכון: הן מהירות, אין להן תלות חיצונית, והן מכסות ניתוב, ולידציה, סדר פעולות וקודי שגיאה.

אבל יש דברים שסטאב לא יכול לבדוק — לא כי הוא חלש, אלא כי הם אינם בקוד אלא בהתנהגות של המסד:

  • אילוץ ייחודיות — אינדקס ייחודי-חלקי כמו one_default_per_user הוא מה שסוגר מרוץ בין שתי בקשות מקבילות. רק המסד יכול לדחות, ו-create_index שהחזיר בלי לזרוק אינו ראיה שהאינדקס נוצר.

  • האם אינדקס בשימוש — רק explain עונה. סטאב מחזיר תוצאה נכונה גם כששאילתה סורקת את כל האוסף.

  • סמנטיקה של BSON — datetime נקטם למילישניות, ובלי tz_aware=True הוא חוזר נאיבי. השוואה בין נאיבי ל-aware זורקת TypeError, ואם היא עטופה ב-except — הבדיקה שנשענת עליה מפסיקה לרוץ בשקט.

  • צינורות aggregation — סטאב שנכתב ביד מבין רק את הצורה שנכתבה בו, ולכן שגיאת תחביר אמיתית עוברת אצלו.

  • בייטים מול תווים — $substrBytes ו-$strLenBytes מודדים בבייטים, $substrCP ו-$strLenCP בתווים, ו-$regexFind מחזיר idx בתווים. על טקסט עברי ערבוב היחידות חותך באמצע אות ומונגו זורקת. אף סטאב בריפו אינו מדגמן את זה — tests/_fake_mongo.py אפילו אין בו aggregate.

הבדיקות האלה חיות בקבצים נפרדים, וכל אחד מהם נשען על משתנה סביבה משלו:

  • tests/test_note_boards_mongo.py — MONGODB_URL, דרך pytestmark שנבדק פעם אחת בטעינת המודול.

  • tests/test_profiler_projection_mongo.py — MONGODB_URL, גם הוא דרך pytestmark, ובנוסף שער גרסה בפיקסצ’ר (ראו למטה).

  • tests/test_snippet_hebrew_offsets_mongo.py — NOTE_FONTS_TEST_MONGO_URI, דרך הפיקסצ’ר wired_mongo שב-tests/conftest.py. אותו פיקסצ’ר משרת גם את שאר הבדיקות שמריצות את הראוטים של הוובאפ מול מסד אמיתי.

  • tests/test_recycle_bin_ttl_index_mongo.py — NOTE_FONTS_TEST_MONGO_URI, ואם הוא ריק MONGODB_URL. ה-pytestmark בודק רק שיש כתובת, והנגישות נבדקת פעם אחת בפיקסצ’ר mongo_client, שמדלג רק על ServerSelectionTimeoutError (גם מארח שאינו נפתר נופל לשם) — אימות שגוי או mongodb+srv:// שאינו נפתר נכשלים ואינם מדלגים. בודק מה השרת עושה עם הבקשה ליצור את אינדקס ה-TTL של סל המיחזור. את המחיקה עצמה הוא אינו בודק: תהליך ה-TTL של השרת רץ פעם בדקה (TTL Indexes), ובדיקה שממתינה לו הייתה נוגעת בתקרת ה-timeout שב-pytest.ini.

המשתנה הנפרד אינו כפילות מיותרת. tests/conftest.py עושה os.environ.setdefault('MONGODB_URL', …) בטעינה, כלומר המשתנה הזה תמיד מוגדר בבדיקות — לערך דמה. פיקסצ’ר שהיה נופל אליו היה מחכה 30 שניות לכתובת שאין מאחוריה שרת, בכל בדיקה, ואז נכשל — ו---maxfail=1 היה עוצר את כל החבילה.

כולם מדלגים כשהמשתנה שלהם ריק או כשהשרת אינו נגיש, כך שהרצה מקומית רגילה נשארת מהירה. שרת שכן נגיש אבל בגרסה נמוכה מדי הוא מקרה אחר לגמרי — שם הבדיקה נכשלת ואינה מדלגת, ראו את הפסקה על גרסת השרת למטה.

אזהרה

ב-CI של ה-PR הן אינן רצות. הג’וב Unit Tests ב-.github/workflows/ci.yml אמנם מרים mongo:8.0 כשירות, אבל הוא רץ ישירות על ה-runner, בלי container:, והשירות מוגדר בלי ports:. לפי תיעוד GitHub Actions, גישה לפי שם השירות עובדת רק כשהג’וב עצמו רץ בקונטיינר; אחרת צריך למפות פורטים ולפנות ל-127.0.0.1:<port>. בלי זה המארח mongodb אינו נפתר כלל ([Errno -3] Temporary failure in name resolution), והבדיקות מדלגות בשקט.

התיקון הוא ports: על השירות ומעבר ל-127.0.0.1 — בדיוק כפי שהג’וב alembic-migrations באותו קובץ כבר עושה עבור postgres. הוא מוצא לסבב נפרד, כי הוא יעיר את הבדיקות האלה ואי אפשר לדעת מראש אילו מהן עוברות.

אחרי מיזוג הן כן רצות, וזה לא אותו קובץ. .github/workflows/deploy.yml מריץ את אותה חבילה על push ל-main, ושם השירות mongodb כן מוגדר עם ports: וה-MONGODB_URL מצביע ל-localhost:27017 — כלומר שרת נגיש, והבדיקות שנשענות על MONGODB_URL רצות במלואן. זה ההסבר לכשל שמופיע ”רק אחרי מיזוג“: אותה חבילה בדיוק, פעם אחת בלי מסד ופעם אחת איתו.

גרסת השרת: 8.0 ומעלה, ולא ”מונגו כלשהו“. הפרודקשן רץ על MongoDB Atlas 8.0, ולכן כל סביבות הבדיקה מרימות mongo:8.0 — .github/workflows/ci.yml, .github/workflows/deploy.yml, docker-compose.yml ו-docker-compose.dev.yml. בדיקה שרצה מול מסד אמיתי ובודקת מנוע אחר מזה שבפרודקשן היא ביטחון שווא, ולא כיסוי. מי שמרים את ה-compose מקומית על volume שנוצר בזמן של 6.0 צריך מעבר חד-פעמי לפני ההרצה הראשונה — ראו התקנה והגדרה.

ל-tests/test_profiler_projection_mongo.py זה קריטי במיוחד: הוא משווה את queryShapeHash שמונגו מחזירה ב-explain, ולפי התיעוד של explain, השדה הזה נוסף ב-MongoDB 8.0. מול 6.0 הוא פשוט אינו חוזר, וההשוואה מתרוקנת מתוכן. הפיקסצ’ר שם קורא buildInfo, ואם הגרסה נמוכה מ-8.0 הוא נכשל בהודעה שאומרת מה גרסת השרת ומה נדרש — ולא מדלג, כי דילוג היה צובע את הריצה בירוק בזמן שההשוואה היחידה שמוכיחה את התיקון אינה מתבצעת.

להרצה מקומית מול שרת אמיתי:

MONGODB_URL='mongodb://127.0.0.1:27017' pytest tests/test_note_boards_mongo.py -v

MONGODB_URL='mongodb://127.0.0.1:27017' pytest tests/test_profiler_projection_mongo.py -v

NOTE_FONTS_TEST_MONGO_URI='mongodb://127.0.0.1:27017' \
    pytest tests/test_snippet_hebrew_offsets_mongo.py -v

NOTE_FONTS_TEST_MONGO_URI='mongodb://127.0.0.1:27017' \
    pytest tests/test_recycle_bin_ttl_index_mongo.py -v

אזהרה

כל הקבצים האלה יוצרים מסד ייעודי משלהם ואינם נוגעים במסד ברירת המחדל: test_note_boards_mongo.py מגריל שם עם התחילית codebot_notes_it_, test_profiler_projection_mongo.py עם התחילית codebot_profiler_it_, test_recycle_bin_ttl_index_mongo.py עם התחילית codebot_recycle_ttl_it_, ו-wired_mongo בונה cktest_<שם קובץ הבדיקה>. ה-teardown של כל קובץ שמגריל שם מוודא שהשם תואם לתחילית לפני drop_database. עם זאת — אל תכוונו את אף אחד משני המשתנים למסד שיש בו נתונים אמיתיים.

GLIBC_TUNABLES בשירותי המונגו

כל שירות שמרים את התמונה mongo, ב-workflows וב-compose, מגדיר GLIBC_TUNABLES: glibc.pthread.rseq=1. בלי זה mongod של 8.0 מסרבת לעלות על חלק מהמחשבים, ובלוג של הקונטיינר מופיעה השורה MongoDB cannot start: Linux kernel versions 6.19 and newer has a known incompatibility with this version of MongoDB ("id":12257600). ב-CI זה נראה כמו Service container mongodb failed בצעד Initialize containers, עוד לפני הצעד הראשון של הג’וב. tests/test_mongo_services_glibc_rseq.py נכשל על כל שירות mongo שאין בו את ההגדרה, גם בקובץ workflow או compose חדש.

מה מונגו בודקת. validateRseqKernelCompat ב-src/mongo/db/startup_check_rseq.cpp (נקרא בתג r8.0.34, הגרסה ש-mongo:8.0 מביאה ב-28.10.2026) עוצרת את העלייה רק כששני תנאים מתקיימים יחד: ה-TCMalloc שבתוך mongod עובד עם מטמון לכל מעבד (per-CPU caches), וגרסת הקרנל ש-uname מחזיר היא בין 6.19.0 ל-7.0.13. בקרנלים האלה המטמון לכל מעבד יכול להפיל את mongod (Production Notes, ‏SERVER-121912). את התנאי הראשון מדליקה התמונה הרשמית: ה-Dockerfile שלה (8.0/Dockerfile בריפו docker-library/mongo) מגדיר ENV GLIBC_TUNABLES glibc.pthread.rseq=0, כדי ש-glibc לא תתפוס את rseq לפני TCMalloc.

למה זה נשבר בלי שום שינוי בריפו. באוקטובר 2026 הקרנל בתמונה של ubuntu-24.04 עבר מ-6.17.0-1022-azure ל-7.0.0-1017-azure (למשל בתמונה 20261026.354), והמעבר בין ה-runners הדרגתי. לפי GitHub, ‏``/proc/version_signature`` מזהה את הקרנל הזה כ-7.0.14, שבו התקלה כבר תוקנה, אבל מונגו קוראת את uname -r, רואה 7.0.0 ומסרבת (actions/runner-images#15005). בזמן המעבר ג’וב נכשל או עובר לפי ה-runner שהוא קיבל, ולכן זה נראה כמו כשל אקראי שעובר בהרצה חוזרת. GitHub כתבו שם שאינם מתכוונים לנעוץ את הקרנל. התיקון של מונגו לקרנלים של אובונטו (SERVER-131779) מתוכנן ל-8.0.35, שעוד לא פורסמה ב-28.10.2026. גם תווית ה-runner הנעוצה לא מגינה מזה — ראו תווית ה-runner.

מה ההגדרה עושה. עם glibc.pthread.rseq=1, ‏glibc רושמת את rseq בעצמה — זו ברירת המחדל שלה (GNU C Library manual, ”POSIX Thread Tunables“) — ו-TCMalloc עובר למטמון לכל חוט: ”Without rseq, TCMalloc uses per-thread caches, which are used by the legacy TCMalloc version“ (TCMalloc Performance Optimization). כך התנאי הראשון של הבדיקה לא מתקיים, והמסלול שהיא מגינה מפניו לא רץ בכלל. משתנה שמוגדר על השירות (env ב-workflow, environment ב-compose) מגיע לקונטיינר כמו docker run --env, וגובר על ה-ENV של התמונה (Dockerfile reference, ”ENV“). mongod מתריעה על זה בעלייה, באזהרה 8718500 שממליצה על glibc.pthread.rseq=0, וזה צפוי.

זו לא הגדרה זמנית. היא לא תלויה בגרסת הקרנל של המחשב ולא באופן שבו מונגו מפענחת אותה, ולכן היא נשארת נכונה גם אחרי 8.0.35. המחיר הוא מנגנון זיכרון פחות יעיל בבדיקות ובפיתוח, ולא מנוע אחר: השאילתות, explain ו-queryShapeHash לא תלויים בו. הפרודקשן רץ על Atlas, וההגדרה הזו לא נוגעת בו. ubuntu-22.04, הפתרון הזמני ש-GitHub מציעים, לא נבחר: הוא מעביר את כל הטסטים למערכת אחרת רק בשביל המונגו, והתמונה הזו עוד תצא משימוש (ראו תווית ה-runner, ”עד מתי תווית ישנה זמינה“).

אימות ביטוי מול גרסת הייצור, בלי לכתוב

הפסקה על גרסת השרת למעלה קובעת 8.0 בכל הסביבות, אבל לא את גרסת המשנה: זו שבייצור לא בהכרח זהה לזו שרצה מקומית, ולפעמים אין שרת מקומי בכלל. כשהנכונות של שינוי תלויה באופן שבו השרת מחשב ביטוי aggregation — $cond בתוך update ב-pipeline, אופרטור שנוסף בגרסה מסוימת, או $strLenCP מול $strLenBytes — אפשר לבדוק את הביטוי על אשכול הייצור עצמו, בקריאה בלבד, דרך הכלי aggregate של MongoDB Atlas MCP. את גרסת האשכול מחזיר הכלי atlas-list-clusters, בשדה mongoDBVersion.

הצורה: aggregate על אוסף קיים, שה-$match הראשון שלו לא מעביר אף מסמך מהאוסף, ואחריו $unionWith בלי coll, שה-pipeline שלו נפתח ב-$documents — מסמכים סינתטיים שעוברים דרך השלבים שבודקים. מה שחוזר הוא המסמכים הסינתטיים בלבד, אחרי השלבים, ושום דבר לא נכתב:

[
  {"$match": {"_id": {"$in": []}}},
  {"$unionWith": {"pipeline": [
    {"$documents": [
      {"case": "same text", "description": "abc", "stored": "abc"},
      {"case": "different text", "description": "abc", "stored": "xyz"},
      {"case": "text that starts with $", "description": {"$literal": "$abc"}, "stored": {"$literal": "$abc"}}
    ]},
    {"$set": {"applied": {"$eq": ["$description", "$stored"]}}}
  ]}}
]

על אשכול הייצור (MongoDB 8.0.34, דרך aggregate של MongoDB Atlas MCP, 5.10.2026) זה החזיר את שלושת המסמכים הסינתטיים בלבד, עם applied שהוא true, false ו-true.

למה דווקא הצורה הזו. $documents מותר רק כשלב הראשון של אגרגציה ברמת המסד (התיעוד של $documents), אבל $unionWith שמשמיט את coll מקבל pipeline שנפתח ב-$documents (התיעוד של $unionWith), וכך אפשר לעבוד דרך אגרגציה של אוסף. אגרגציה ברמת המסד — הכלי aggregate-db — נדחתה בחיבור שלנו, כי אין לו הרשאת changeStream (5.10.2026).

ולמה רשימה ריקה בשלב הראשון. שום ערך אינו נמצא ברשימה ריקה, ולכן {"_id": {"$in": []}} לא מעביר אף מסמך, בכל אוסף ומה שלא יהיה בו. _id שנבחר כי ”אין כזה“, כמו "no-such-document", לא מבטיח את זה: אם יש באוסף מסמך כזה, הוא חוזר לצד המסמכים הסינתטיים. {"$expr": false} ו-{"$expr": {"$eq": [1, 0]}} כן שקריים תמיד, אבל השרת לא מזהה את זה מראש: הוא קורא את כל האוסף ובודק את התנאי מסמך אחר מסמך, בזמן שב-$in ריק הוא מזהה מראש שאף מסמך לא יעבור, ולא קורא אף אחד. נמדד ב-explain: על הייצור (8.0.34, 5.10.2026, במצב queryPlanner, שאינו מריץ את השאילתה) התוכנית של $in ריק היא EOF ושל שני ה-$expr היא COLLSCAN; ומקומית (8.0.32, במצב executionStats) שני ה-$expr בדקו כל מסמך באוסף, ו-$in ריק אף לא אחד.

גם אופרטור של שאילתה נבדק כך: $match אחרי $documents מחזיר רק את המסמכים הסינתטיים שהוא תופס. כך אפשר לבדוק טענה על סמנטיקה של סינון — למשל אם $nin: [null, ""] תופס מסמך שאין בו את השדה — עם מסמך שיש בו את השדה, מסמך בלעדיו ומסמך שבו הוא null. על הייצור (8.0.34, 5.10.2026) נתפס רק הראשון מהשלושה. זה הפוך ממה שמשתמע מ-התיעוד של $nin, שלפיו הוא בוחר גם מסמך שהשדה לא קיים בו, ומתיישב עם התיעוד של null ושדות חסרים: השוואה ל-null תופסת גם שדה חסר, ולכן null ברשימה פוסל גם אותו. $documents לא מוחק שדה שערכו null — בלי ה-$match, $type החזיר null למסמך השלישי ו-missing לשני — כך שאלה באמת שני מקרים נפרדים.

שני דברים שצריך לשמור עליהם:

  • מחרוזת שמתחילה בסימן דולר בתוך $documents נקראת כביטוי ולא כטקסט, וביטוי שאינו מתפרש מול מסמך נוכחי נכשל (לפי התיעוד של $documents שלמעלה). טקסט כזה עוטפים ב-{"$literal": ...}, כמו במסמך השלישי בדוגמה.

  • רק קריאה. בלי $out ובלי $merge, שכותבים, ובלי אף כלי כתיבה של MongoDB Atlas MCP מול הייצור.

מה זה בודק, ומה לא. זה בודק את הביטוי — האופרטורים, נתיבי השדות והתנאים — על הגרסה שרצה בייצור. זה לא בודק את הכתיבה עצמה: מה find_one_and_update מחזיר, את modified_count, או אילו מסמכים הכתיבה תתפוס. את אלה מודדים מול mongod מקומי, בגרסה הקרובה ביותר שאפשר, כמו בפסקאות שלמעלה. כך נבדק ה-$cond של update_file_metadata_in ב-#3526: הכתיבה נמדדה מול mongod 8.0.32 מקומי, והביטויים — גם על 8.0.34 של הייצור.

כיסוי בדיקות (pytest-cov)

  • הפרויקט מגדיר pytest-cov ב-pytest.ini. אם חסר, התקינו: pip install pytest-cov.

  • ב-CI הוא נמדד רק בחלק מהמסלולים של unit-tests — ראו CI/CD Guide.

  • דוחות:

pytest --cov=. --cov-report=term-missing --cov-report=xml

CI נתמך

  • אילו ג’ובים רצים על PR ואילו סטטוסים הוא חייב לעבור — ב-CI/CD Guide. העמוד הזה מפנה לשם במקום להחזיק עותק של הרשימה.

טסטי Markdown כבדים (md_heavy)

טסטים שמסומנים ``md_heavy`` רצים ב-CI במסלול משלהם, במקביל לשאר הטסטים. אלה טסטי פרסר ה-Markdown שעיקר העבודה שלהם הוא החישוב עצמו: השוואה לאורקל cmark-gfm (tests/test_md_parser_oracle.py), קלט ענק בתקרות של הפרסר, והטסטים של סקריפטי המדידה (scripts/md_parser_upgrade_zero_diff.py ו-scripts/measure_md_parse_cost.py). הסימון רשום ב-pytest.ini. הוא מונח על הקובץ כולו (pytestmark) כשכל הקובץ מהסוג הזה, ועל טסט בודד כשרק הוא כזה — כמו שני טסטי התקרה ב-tests/test_md_parser.py.

  • pytest בלי -m מריץ את כולם, כולל md_heavy. כדי להריץ רק חלק אחד:

    # רק הכבדים — מה שהמסלול md-heavy מריץ ב-CI
    pytest -m md_heavy
    
    # כל השאר — מה שהמסלול הרגיל מריץ ב-CI
    pytest -m "not md_heavy"
    
  • ב-CI הג’וב unit-tests ב-.github/workflows/ci.yml רץ בשני מסלולים לכל גרסת פייתון, וכל מסלול מדווח סטטוס חובה משלו (ראו CI/CD Guide).

  • מתי מסמנים טסט חדש: כשהוא מאותו סוג — השוואה לאורקל, קלט בתקרות של הפרסר, או סקריפט מדידה. טסט איטי מסוג אחר אינו שייך לכאן: המסלול הזה אינו מקום לכל מה שאיטי.

  • אין קשר ל-``heavy``. heavy שייך לטסטי הביצועים (-m performance), ראו בדיקות ביצועים (Performance Tests).

  • מסלול שלא נבחר בו אף טסט נכשל ואינו עובר בשקט: pytest יוצא בקוד 5 כשלא נאסף אף טסט, גם כשכולם סוננו ב--m (נמדד ב-pytest 8.4.2). לכן שם סימון ששונה ב-ci.yml בלי הטסטים, או בכל הטסטים בלי ci.yml, מפיל את המסלול md-heavy. טסט בודד שהסימון שלו חסר או שגוי אינו נתפס כך: הוא עובר למסלול הרגיל ורץ שם, לאט יותר. tests/test_required_checks_are_listed.py מקבע את קוד היציאה, ובודק שהביטויים של שני המסלולים משלימים זה את זה, כך שכל טסט נבחר במסלול אחד בדיוק.

בדיקות דפדפן, ותקרת הזמן

בדיקות הדפדפן מדולגות כשאין דפדפן, וההכרעה נעשית פעם אחת לכל הריצה. הפיקסצ’ר chromium_executable ב-tests/conftest.py מנסה להרים Chromium פעם אחת, ואם אין — כל בדיקות הדפדפן מדולגות שם, לפני שאף אחת מהן מרימה תהליך דרייבר של Playwright בעצמה. ל-CI אין שלב שמתקין דפדפן, ולכן זה המצב הרגיל שם ולא תקלה — והריצה אומרת את זה במפורש בסיכום, כדי שלא ייראה כאילו הבדיקות רצו.

מכאן נובע שהכיסוי של בדיקות הדפדפן ב-CI הוא אפס. מי שרוצה להריץ אותן מקומית צריך דפדפן מותקן ואת PLAYWRIGHT_BROWSERS_PATH מכוון אליו; בלי זה הן מדולגות בשקט מוצהר.

ובדיקה שחורגת מהתקרה נכשלת בשמה, ואינה הורגת את התהליך. pytest.ini קובע timeout = 60 ואינו קובע timeout_method — ההשמטה מכוונת, ו-pytest-timeout בוחר בעצמו לפי הפלטפורמה. בשיטה thread, שהייתה כתובה שם קודם, התוסף קורא os._exit: הבדיקה אינה נכשלת אלא הורגת את התהליך שמריץ אותה.

זה מסביר את ההודעה node down: Not properly terminated שמופיעה בלוגים של ריצות עבר תחת pytest-xdist. היא באה מה-controller, שרואה תהליך שנעלם, ואינה נוקבת בשם הבדיקה — כי ה-worker כותב את המחסנית ל-stderr שלו ויוצא לפני שהפלט נשטף. הסימן שמזהה אותה בלוג הוא הפער: היא מופיעה בדיוק timeout שניות אחרי השורה האחרונה של אותו worker.

Sentry בבדיקות

אף בדיקה לא משאירה Sentry מוכן להידלק בבדיקות שאחריה. tests/_sentry_isolation.py נרשם מ-tests/conftest.py, ולכן פעיל בכל ריצה שאוספת בדיקות מתוך tests/ — כולל הריצה המלאה — ובריצה כזו הוא חל על כל בדיקה, גם על אלה שמחוץ ל-tests/ (testpaths ב-pytest.ini כולל את .). בתחילת הריצה הוא מסיר את SENTRY_DSN מהסביבה, כך שגם כתובת אמיתית מהמעטפת של מי שמריץ לא מגיעה לבדיקות. אחרי כל בדיקה, כשכל הפיקסצ’רים שלה כבר פורקו — כולל monkeypatch — הוא בודק שלא נשאר SENTRY_DSN בסביבה ושאין לקוח Sentry חי. אם נשאר, המצב מוחזר לנקי, והבדיקה שהשאירה אותו נכשלת בשמה (ERROR at teardown) עם הסבר מה לעשות במקום.

למה. טסט הטפטוף של PUT /api/agent/upload ב-tests/test_mcp_uploads.py עבר לבדו ונפל רק בריצה הסדרתית של deploy.yml, אחרי שתי בדיקות אחרות. אחת השאירה SENTRY_DSN בסביבה; השנייה טענה מחדש את main, ש-main.py קורא ל-init_sentry() ברמת המודול (#3512), ומשם נדלק Sentry אמיתי עם כל האינטגרציות שהוא מדליק לבד כשהספרייה שלהן מותקנת — Starlette, pymongo, redis, httpx. אינטגרציית ה-Starlette קוראת את גוף הבקשה לפני ה-route ובלי דדליין (StarletteRequestExtractor.extract_request_info, נקרא ב-sentry-sdk 2.42.1; #3513), ולכן הטסט שבודק את הדדליין של ה-route נתקע — והשגיאה הופיעה ב-authenticate_bearer, רחוק משתי הבדיקות שגרמו לה. ב-ci.yml הבדיקות מתחלקות בין כמה תהליכים (-n auto), ולכן שם השרשרת תלויה בחלוקה, ובריצה של ה-PR היא לא נפגשה.

איך כותבים בדיקה שנוגעת ב-Sentry. משתנה סביבה — רק ב-monkeypatch.setenv. השמה ישירה ל-os.environ נשארת לכל שאר הריצה, ו-monkeypatch.delenv אחרי השמה ישירה אינו ניקוי: הוא זוכר את הערך שמצא ומחזיר אותו בסוף הבדיקה — כך בדיוק דלף SENTRY_DSN מ-tests/test_db_sentry_checks.py. בדיקה שבודקת את האתחול מחליפה את sentry_sdk.init בדמה דרך monkeypatch (כמו tests/test_observability_new.py), ובדיקה שחייבת לקוח אמיתי קוראת בסופה ל-_sentry_isolation.shut_down_sentry(), שמנתקת מכל ה-scopes כל לקוח שרשום בהם וסוגרת כל אחד מהם. close() לבדו אינו מספיק: לקוח סגור שעדיין רשום ב-scope ממשיך להיחשב פעיל (_Client.is_active, נקרא ב-sentry-sdk 2.42.1), והשומר יכשיל את הבדיקה.

הבדיקה נעשית אחרי כל בדיקה, ולכן גם פיקסצ’ר ברמת מודול שמגדיר SENTRY_DSN ייתפס אחרי הבדיקה הראשונה שלו. זה מכוון: SENTRY_DSN בסביבה לאורך כמה בדיקות הוא בדיוק המצב שבו טעינה מחדש של main מדליקה Sentry. השומר מכסה את SENTRY_DSN ואת הלקוח בלבד — דליפה של משתני סביבה אחרים בין בדיקות היא #3511. ההתנהגות מקובעת ב-tests/test_sentry_isolation.py, שמריץ סשן pytest פנימי ובודק גם שבלי השומר הדליפה כן עוברת לבדיקה הבאה.

מצב שקוד הייצור זוכר בזיכרון התהליך

מודול שזוכר משהו בגלובלים זוכר אותו גם בין בדיקות. בפרודקשן זו הכוונה: _ensure_indexes ב-webapp/sticky_notes_api.py בונה את אינדקסי הפתקים פעם אחת לתהליך, ואחרי בנייה שנכשלה אינו מנסה שוב לפני _INDEX_RETRY_AFTER (ראו Sticky Notes Warmup – פתרון ביצועים משולב). בבדיקות תהליך אחד מריץ קבצים רבים ברצף, ובדיקה שהריצה את הבנייה מול stub משאירה את המצב הזה לבדיקה שאחריה.

כך נפלו בדיקות האינדקסים ב-tests/test_note_boards_mongo.py כשרצו אחרי tests/test_sticky_note_reminders.py באותו תהליך: בדיקות התזכורות משאירות את חלון ההמתנה פתוח, והפיקסצ’ר indexed_db איפס את הדגלים שהכיר — ולא את החלון. _ensure_indexes יצא מוקדם, ואף אינדקס לא נבנה. לבדו, ובסדר ההפוך, הקובץ עבר.

האיפוס חי ליד המצב, ולא בקבצי הטסט. reset_index_state_for_tests, באותו מודול, מחזירה את כל המצב הזה לנקודת ההתחלה — כולל הדגל המשותף בקאש, שהיא מוחקת וקוראת בחזרה — ופיקסצ’ר אוטומטי ב-conftest.py שבשורש קורא לה לפני כל בדיקה ואחריה. בדיקה אינה מאפסת בעצמה את הגלובלים האלה: רשימה בכל קובץ נסחפת ברגע שנוסף שומר, וזה בדיוק מה שקרה ל-indexed_db. tests/test_sticky_notes_index_state.py גוזר מקוד המקור את הגלובלים שהבנייה כותבת, ונופל אם האיפוס אינו מחזיר אחד מהם לערך שלו בטעינת המודול. מצב חדש מאותו סוג, במודול אחר, כדאי לבנות באותה צורה.

ואיפוס הוא גבול גם לעבודה שבאמצע. חוט שהתחיל לפני האיפוס — חימום של kickoff_index_warmup שתוזמן ועוד ישן, בקשה שממתינה לנעילה, בנייה שנכשלת בזמן שהאיפוס ממתין לה — ממשיך לרוץ אחריו, ובלי הגנה היה בונה או כותב לתוך הבדיקה הבאה, מול ה-get_db שהיא החליפה. לכן האיפוס מקדם את _INDEX_STATE_GENERATION, וכל קריאה ל-_ensure_indexes בודקת תחת הנעילה שהיא עדיין מהדור הנוכחי לפני שהיא בונה או כותבת. וגם המחיקה של הדגל המשותף מאומתת מול הלקוח שמאחורי CacheManager ולא דרכו: CacheManager.get מחזיר None גם כש-Redis לא ענה, ואיפוס שקורא דרכו היה מאשר מחיקה שלא קרתה. מה שהדור אינו מכסה, ולמה, מתועד ב-docstring של reset_index_state_for_tests.

ספרייה חסרה בבדיקה

מדמים ספרייה חסרה עם ``None`` ב-``sys.modules``, ולא במחיקה ממנו. כשהערך של שם ב-sys.modules הוא None, הייבוא שלו זורק ModuleNotFoundError, בדיוק כמו כשהחבילה לא מותקנת. מחיקה (sys.modules.pop) לא מדמה כלום: הייבוא הבא פשוט טוען את החבילה מהדיסק. את השינוי עושים דרך monkeypatch.setitem ו-monkeypatch.delitem, שמחזירים את sys.modules למצב הקודם בסוף הבדיקה. שינוי ישיר נשאר לכל שאר הריצה.

למה. tests/test_code_processor_optional_deps.py מחק מ-sys.modules את Pillow ועוד ספריות אופציונליות, כדי לבדוק את החלופות ב-code_processor.py. הוא לא הגיע אליהן אף פעם, כי הספריות פשוט נטענו מחדש. אבל הוא מחק את PIL.Image והשאיר בזיכרון את התוספים שלו (PIL.JpegImagePlugin ואחרים). תוסף של Pillow נרשם ב-PIL.Image כשהקוד שלו רץ, כלומר רק בייבוא הראשון שלו (נקרא ב-Pillow 12.0.0). לכן הבדיקה הבאה שייבאה את Pillow קיבלה PIL.Image חדש בלי אף פורמט רשום, ו-Image.open נכשל ב-UnidentifiedImageError ב-tests/test_home_page.py, רחוק מהבדיקה שגרמה לזה. זה קרה רק בריצה הסדרתית של deploy.yml: ב-ci.yml הבדיקות מתחלקות בין כמה תהליכים (-n auto), ולכן השרשרת תלויה בחלוקה, ובריצות שם היא לא נפגשה.

ועוד שלושה דברים שהבדיקה המתוקנת עושה, ושכדאי לעשות בכל בדיקה כזו:

  • לפני החסימה טוענים את המודול הנבדק כרגיל. כך התלויות שלו כבר בזיכרון במצבן הרגיל. אחרת, כשהבדיקה רצה לבד, הן נטענות לראשונה בזמן החסימה, ונשארות כך לבדיקות שאחריה.

  • חוסמים גם את תת-המודולים שכבר טעונים. from pygments.lexers import ... מחזיר את pygments.lexers מהזיכרון בלי לבדוק את pygments עצמו.

  • בודקים שהחלופות באמת נכנסו לפעולה. בלי בדיקה כזו, חסימה שלא עובדת עוברת בשקט, וזה בדיוק מה שקרה לבדיקה הישנה.

הקפאת זמן ותהליכוני רקע

הקפאת זמן מקפיאה את השעון של כל התהליך, לא רק של הטסט. freeze_time של freezegun מחליף את time.monotonic לכל התהליכונים, ובזמן ההקפאה הוא מחזיר את התאריך המוקפא בשניות. תהליכון רקע שמתחיל באותו רגע לחכות למשהו מחשב לו מועד אחרון מהשעון המזויף — ואחרי ההקפאה השעון האמיתי לא מגיע לשם לעולם. כך נתקעו ב-CI של #3585 שמונה טסטים: חיפוש שרת של pymongo שהתחיל בתוך freeze_time לא ויתר, והחזיק את _DB_INIT_LOCK של get_db.

  • tests/conftest.py מוסיף את pymongo לרשימת ההתעלמות של freezegun (freezegun.configure(extend_ignore_list=...)), כך שהדרייבר רואה תמיד שעון אמיתי. tests/test_freezegun_leaves_the_mongo_driver_clock_alone.py מוכיח את זה, ונופל בלי ההגדרה.

  • ספרייה נוספת שממתינה לפי השעון בתהליכון רקע, ונתקעת באותה צורה, מתווספת לאותה רשימה — ולא נעקפת בטסט שמקפיא.

  • שולח הפושים כבר לא קם בתהליך הטסטים: הוא קם רק בתהליך השרת של הוובאפ (עובדי Push). זה לא נכון לכל תהליכוני הרקע של webapp.app: חלקם עדיין קמים בכל ייבוא, למשל בדיקת מודל ה-embeddings (_maybe_start_embedding_health_check) כשמוגדר GEMINI_API_KEY. לכן ההחרגה של pymongo שבתחילת הסעיף היא ההגנה הכללית מפני התקיעה, ולא השומר של השולח.

בדיקות ביצועים (Performance)

  • מרקרים:

    [pytest]
    markers =
        performance: בדיקות ביצועים
        heavy: טסטים כבדים (מדולגים כשמבקשים רק קלים)
    
  • הרצות מקומיות:

    # הכל
    pytest -q -m performance
    
    # רק קלים
    ONLY_LIGHT_PERF=1 pytest -q -m performance
    
  • CI: - ברירת מחדל מריץ הכל. - PR Draft + תווית perf-light מריץ רק קלים. - זמני ריצה נשמרים כארטיפקטים: durations.json, durations-summary.json.

  • דוחות/מדידות:

    pytest -m performance --durations=0 --json-report --json-report-file=durations.json
    cat durations.json | jq '.summary.durations' > durations-summary.json
    

קישורים

העמוד הזה הוא נקודת הכניסה לטסטים, ולכן הוא מפנה גם לעמודים שנוגעים בטסטים מזוויות אחרות, כך שמי שהגיע לכאן ראשון יוכל למצוא אותם בקלות.