14 - Testing/15 - Testing.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Тестване"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Осигуряването и управлението на качеството е важен аспект от разработката на софтуер. За целта се използват различни методи, които главно се делят на end-to-end, integration и unit тестове. За първите две отговорността обикновено е у QA инженера, докато unit тестовете трябва да се пишат от разработчиците, понеже са white-box тестове (т.е. тестващия трябва да има знание всеки компонент вътрешно как изглежда).\n",
    "\n",
    "![различни видове тестове](assets/tests.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Целта на unit test-овете е да проиграят всички възможни ключови ситуации, свързани с **един** конкретен компонент и да проверят дали се държи очаквано при тях."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Before"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В папката `13 - Modules` има пример за тестване на един компонент, макар и примитвен такъв. Намира се в `game.engine` модула:\n",
    "\n",
    "```python\n",
    "if __name__ == \"__main__\":\n",
    "    # Executed when running `python3 -m game.engine`\n",
    "    \n",
    "    from game.players.mock_player import MockPlayer\n",
    "\n",
    "    print(\"Testing win case...\")\n",
    "    player_win = MockPlayer(1, \"oba\")\n",
    "    engine_win = BesenitsaEngine(\"foobar\", player_win)\n",
    "\n",
    "    assert engine_win.guess() == GameState.ONGOING\n",
    "    assert engine_win.guess() == GameState.ONGOING\n",
    "    assert engine_win.guess() == GameState.WON\n",
    "    print(\"Test OK.\")\n",
    "\n",
    "    print(\"Testing lose case...\")\n",
    "    player_lose = MockPlayer(3, \"asdg\")\n",
    "    engine_lose = BesenitsaEngine(\"foobar\", player_lose)\n",
    "\n",
    "    assert engine_lose.guess() == GameState.ONGOING\n",
    "    assert engine_lose.guess() == GameState.ONGOING\n",
    "    assert engine_lose.guess() == GameState.ONGOING\n",
    "    assert engine_lose.guess() == GameState.LOST\n",
    "    print(\"Test OK.\")\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Тестването по този начин, освен че може да бъде по-трудоемко и по-трудно за проследяване и изпълнение за по-сложни ситуации и проекти, има и друг недостатък, че когато нещо не е както трябва (някой `assert` не минава), нямаме детайлна информация за това кое не е правилно. Например, ако `engine_win.guess()` връща `GameState.LOST` вместо `GameState.WON`, ще получим само `AssertionError`, без да знаем какъв е точно върнатия резултат на `engine_win.guess()` и защо не е равен на `GameState.WON`.\n",
    "\n",
    "Още повече, най-главния недостатък на този начин на \"тестване\" е че така се изпълняват последователно тестовете и ако един гръмне, то другите няма да се изпълнят. А ние не искаме това да е така - трябва всеки тест да се изпълнява независимо от другите - за предпочитане в отделни нишки, без споделена памет и без споделено състояние и т.н."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## After (a.k. unit testing frameworks in Python)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Съществуват няколко основни test runner-а в Python света, като `unittest`, `pytest`, `nose`, `nose2` и други. Ще разгледаме двата най-използвани - `unittest` и `pytest`."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `unittest`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`unittest` е ***вградена*** библиотека (от Python 2.1 насам), която ни предоставя както framework, така и runner за тестове."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Особености\n",
    "\n",
    "* Всеки тестови случай е метод на клас, наследяващ `unittest.TestCase`\n",
    "* Използват се `assert...` методи на класа вместо `assert` ключовата дума\n",
    "* Трябва всеки тестови модул да извика `unittest.main()` когато бъде изпълнен директно"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако трябва горните два test case-a да ги пренапишем с `unittest`, ще изглеждат по този начин:\n",
    "\n",
    "```python\n",
    "import unittest\n",
    "\n",
    "from tests.mocks.mock_player import MockPlayer  # moved inside the tests/ package\n",
    "from game.engine import BesenitsaEngine, GameState\n",
    "\n",
    "class EngineTests(unittest.TestCase):\n",
    "    def test_foobar_win(self):\n",
    "        player_win = MockPlayer(1, \"oba\")\n",
    "        engine_win = BesenitsaEngine(\"foobar\", player_win)\n",
    "\n",
    "        self.assertEqual(engine_win.guess(), GameState.ONGOING)\n",
    "        self.assertEqual(engine_win.guess(), GameState.ONGOING)\n",
    "        self.assertEqual(engine_win.guess(), GameState.WON)\n",
    "\n",
    "    def test_foobar_lose(self):\n",
    "        player_lose = MockPlayer(3, \"asdg\")\n",
    "        engine_lose = BesenitsaEngine(\"foobar\", player_lose)\n",
    "\n",
    "        self.assertEqual(engine_lose.guess(), GameState.ONGOING)\n",
    "        self.assertEqual(engine_lose.guess(), GameState.ONGOING)\n",
    "        self.assertEqual(engine_lose.guess(), GameState.ONGOING)\n",
    "        self.assertEqual(engine_lose.guess(), GameState.LOST)\n",
    "\n",
    "if __name__ == '__main__':\n",
    "    unittest.main()\n",
    "```\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`self.assertEqual` е един от многото методи, които предоставя `unittest` за проверка на различни условия. Пълен списък може да намерите [тук](https://docs.python.org/3/library/unittest.html#assert-methods). Те са:\n",
    "\n",
    "* `assertEqual(a, b)` - проверява дали `a == b`\n",
    "* `assertTrue(x)` - проверява дали `bool(x) is True`\n",
    "* `assertFalse(x)` - проверява дали `bool(x) is False`\n",
    "* `assertIs(a, b)` - проверява дали `a is b`\n",
    "* `assertIsNot(a, b)` - проверява дали `a is not b`\n",
    "* `assertIsNone(x)` - проверява дали `x is None`\n",
    "* `assertIsNotNone(x)` - проверява дали `x is not None`\n",
    "* `assertIn(a, b)` - проверява дали `a in b`\n",
    "* `assertNotIn(a, b)` - проверява дали `a not in b`\n",
    "* `assertIsInstance(a, b)` - проверява дали `isinstance(a, b)`\n",
    "* `assertNotIsInstance(a, b)` - проверява дали `not isinstance(a, b)`\n",
    "\n",
    "Ползата им можем да видим например ако променим във `test_foobar_win` да очакваме накрая `GameState.LOST` вместо `GameState.WON` (или по някакъв друг начин променим кода така, че да имаме грешно поведение спрямо тестовете). Това output-ът от този тест ще е достатъчно информативен (сравнението показва всички разлики между двата обекта):\n",
    "\n",
    "```\n",
    "======================================================================\n",
    "FAIL: test_foobar_win (test_engine.EngineTests)\n",
    "----------------------------------------------------------------------\n",
    "Traceback (most recent call last):\n",
    "  File \"/Users/alexander.ignatov/Desktop/besenitsa/tests/test_engine.py\", line 25, in test_foobar_win\n",
    "    self.assertEqual(engine_win.guess(), GameState.LOST)\n",
    "AssertionError: <GameState.WON: 1> != <GameState.LOST: 2>\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Команди"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Директно изпълнение на един файл с тестове:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      ".\n",
      "----------------------------------------------------------------------\n",
      "Ran 1 test in 0.000s\n",
      "\n",
      "OK\n"
     ]
    }
   ],
   "source": [
    "!python3 test_single_simple_unittest.py"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Изпълнение на един модул с тестове:\n",
    "\n",
    "*Важно*: ⚠️ При достъп през пакет (т.е. с точка, както по-долу имаме пакетът `tests`, в който се намира `test_engine` модула) трябва пакетът да съдържа `__init__.py` файл, макар и празен (това показва, че пакетът **не е** само т.нар. **namespace** package)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      ".....\n",
      "----------------------------------------------------------------------\n",
      "Ran 5 tests in 0.000s\n",
      "\n",
      "OK\n"
     ]
    }
   ],
   "source": [
    "!python3 -m unittest tests.test_engine"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Автоматично откриване на всички тестове в *текущата* директория:\n",
    "\n",
    "(търси всички python файлове, започващи с `test`, и ги изпълнява)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      ".......\n",
      "----------------------------------------------------------------------\n",
      "Ran 7 tests in 0.000s\n",
      "\n",
      "OK\n"
     ]
    }
   ],
   "source": [
    "!python3 -m unittest discover"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Автоматично откриване на всички тестове в *дадена* директория (в случая `tests`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "......\n",
      "----------------------------------------------------------------------\n",
      "Ran 6 tests in 0.000s\n",
      "\n",
      "OK\n"
     ]
    }
   ],
   "source": [
    "!python3 -m unittest discover -s tests"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Изпълнение на всички файлове с име, започващо с  `test_`, в директория, наречена `tests`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "......\n",
      "----------------------------------------------------------------------\n",
      "Ran 6 tests in 0.000s\n",
      "\n",
      "OK\n"
     ]
    }
   ],
   "source": [
    "!python3 -m unittest discover -s tests -p \"test_*.py\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Вербозен output се дава с добавяне на параметъра `-v`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "test_firstGuess_isE (test_ai_player.TestAIPlayer) ... ok\n",
      "test_cat_lose (test_engine.EngineTests) ... ok\n",
      "test_cat_win (test_engine.EngineTests) ... ok\n",
      "test_foobar_lose (test_engine.EngineTests) ... ok\n",
      "test_foobar_win (test_engine.EngineTests) ... ok\n",
      "test_initialWord_isMaskedCorrectly (test_engine.EngineTests) ... ok\n",
      "\n",
      "----------------------------------------------------------------------\n",
      "Ran 6 tests in 0.000s\n",
      "\n",
      "OK\n"
     ]
    }
   ],
   "source": [
    "!python3 -m unittest discover -s tests -v"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако кодът не се намира в корена на директорията, а например в папка, наречена `src`, можем да добавим параметър `-t src`, за да кажем на `unittest` да изпълни тестовете оттам:\n",
    "\n",
    "```bash\n",
    "python3 -m unittest discover -s tests -t src\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `pytest`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Особености"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pytest` **не е** вградена библиотека, но има някои предимства пред `unittest`, като:\n",
    "\n",
    "* по-малко boilerplate (не се наследява от `unittest.TestCase`, използва се `assert` ключовата дума, няма main entry point)\n",
    "* възможност за филтриране на тестове\n",
    "* екосистема от стотици плъгини за разширяване на функционалността"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Хубаво е да се отбележи, че тестове, написани с `unittest` са **съвместими** с `pytest` и могат да се изпълняват с него. Обратното, обаче, не е вярно."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако трябва да пренапишем двата теста от по-горе за `pytest`, файлът би изглеждал така:\n",
    "\n",
    "```python\n",
    "\n",
    "from tests.mocks.mock_player import MockPlayer\n",
    "from game.engine import BesenitsaEngine, GameState\n",
    "\n",
    "def test_foobar_win():\n",
    "    player_win = MockPlayer(1, \"oba\")\n",
    "    engine_win = BesenitsaEngine(\"foobar\", player_win)\n",
    "\n",
    "    assert engine_win.guess() == GameState.ONGOING\n",
    "    assert engine_win.guess() == GameState.ONGOING\n",
    "    assert engine_win.guess() == GameState.WON\n",
    "\n",
    "def test_foobar_lose():\n",
    "    player_lose = MockPlayer(3, \"asdg\")\n",
    "    engine_lose = BesenitsaEngine(\"foobar\", player_lose)\n",
    "\n",
    "    assert engine_lose.guess() == GameState.ONGOING\n",
    "    assert engine_lose.guess() == GameState.ONGOING\n",
    "    assert engine_lose.guess() == GameState.ONGOING\n",
    "    assert engine_lose.guess() == GameState.LOST"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Команди"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Преди всичко, трябва да инсталираме `pytest` чрез PIP например:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requirement already satisfied: pytest in /Users/alexander.ignatov/Documents/PythonCourse2022/venv/lib/python3.10/site-packages (7.2.0)\n",
      "Requirement already satisfied: iniconfig in /Users/alexander.ignatov/Documents/PythonCourse2022/venv/lib/python3.10/site-packages (from pytest) (1.1.1)\n",
      "Requirement already satisfied: pluggy<2.0,>=0.12 in /Users/alexander.ignatov/Documents/PythonCourse2022/venv/lib/python3.10/site-packages (from pytest) (1.0.0)\n",
      "Requirement already satisfied: exceptiongroup>=1.0.0rc8 in /Users/alexander.ignatov/Documents/PythonCourse2022/venv/lib/python3.10/site-packages (from pytest) (1.1.0)\n",
      "Requirement already satisfied: packaging in /Users/alexander.ignatov/Documents/PythonCourse2022/venv/lib/python3.10/site-packages (from pytest) (22.0)\n",
      "Requirement already satisfied: tomli>=1.0.0 in /Users/alexander.ignatov/Documents/PythonCourse2022/venv/lib/python3.10/site-packages (from pytest) (2.0.1)\n",
      "Requirement already satisfied: attrs>=19.2.0 in /Users/alexander.ignatov/Documents/PythonCourse2022/venv/lib/python3.10/site-packages (from pytest) (22.2.0)\n",
      "\n",
      "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m A new release of pip available: \u001b[0m\u001b[31;49m22.2.2\u001b[0m\u001b[39;49m -> \u001b[0m\u001b[32;49m22.3.1\u001b[0m\n",
      "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m To update, run: \u001b[0m\u001b[32;49mpip install --upgrade pip\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "!pip install pytest"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Това ни предоставя и командата `pytest`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pytest 7.2.0\n"
     ]
    }
   ],
   "source": [
    "!pytest --version"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Извикването на командата `pytest` е почти еквивалентно на това да се изпълни модула чрез `python3 -m pytest`. Единствената разлика е, че втория начин ще добави и текущата директория към `sys.path`."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Директно изпълнение на един файл с тестове:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[1m============================= test session starts ==============================\u001b[0m\n",
      "platform darwin -- Python 3.10.8, pytest-7.2.0, pluggy-1.0.0\n",
      "rootdir: /Users/alexander.ignatov/Documents/PythonCourse2022/15 - Testing\n",
      "collected 1 item                                                               \u001b[0m\n",
      "\n",
      "test_single_simple_pytest.py \u001b[32m.\u001b[0m\u001b[32m                                           [100%]\u001b[0m\n",
      "\n",
      "\u001b[32m============================== \u001b[32m\u001b[1m1 passed\u001b[0m\u001b[32m in 0.00s\u001b[0m\u001b[32m ===============================\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "!pytest test_single_simple_pytest.py"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Изпълнение на всички тестове в директория `tests`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[1m============================= test session starts ==============================\u001b[0m\n",
      "platform darwin -- Python 3.10.8, pytest-7.2.0, pluggy-1.0.0\n",
      "rootdir: /Users/alexander.ignatov/Documents/PythonCourse2022/15 - Testing\n",
      "collected 6 items                                                              \u001b[0m\n",
      "\n",
      "tests/test_ai_player.py \u001b[32m.\u001b[0m\u001b[32m                                                [ 16%]\u001b[0m\n",
      "tests/test_engine.py \u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m                                               [100%]\u001b[0m\n",
      "\n",
      "\u001b[32m============================== \u001b[32m\u001b[1m6 passed\u001b[0m\u001b[32m in 0.01s\u001b[0m\u001b[32m ===============================\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "!pytest tests"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Изпълнение само на тестове, отговарящи на даден критерий (в случая: всички от `EngineTests` класа, които нямат `foobar` в името си):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[1m============================= test session starts ==============================\u001b[0m\n",
      "platform darwin -- Python 3.10.8, pytest-7.2.0, pluggy-1.0.0\n",
      "rootdir: /Users/alexander.ignatov/Documents/PythonCourse2022/15 - Testing\n",
      "collected 8 items / 5 deselected / 3 selected                                  \u001b[0m\n",
      "\n",
      "tests/test_engine.py \u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m                                                 [100%]\u001b[0m\n",
      "\n",
      "\u001b[32m======================= \u001b[32m\u001b[1m3 passed\u001b[0m, \u001b[33m5 deselected\u001b[0m\u001b[32m in 0.01s\u001b[0m\u001b[32m ========================\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "!pytest -k \"EngineTests and not foobar\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Изпълнение по Node ID:\n",
    "\n",
    "(на всеки открит тест от `pytest` бива сложено Node ID, което се съставя от името на файла, последвано от специфичния \"път\", който води до scope-а на теста, т.е. имена на класове, методи/функции и евентуални техни параметри, разделени от `::`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[1m============================= test session starts ==============================\u001b[0m\n",
      "platform darwin -- Python 3.10.8, pytest-7.2.0, pluggy-1.0.0\n",
      "rootdir: /Users/alexander.ignatov/Documents/PythonCourse2022/15 - Testing\n",
      "collected 5 items                                                              \u001b[0m\n",
      "\n",
      "tests/test_engine.py \u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m.\u001b[0m\u001b[32m                                               [100%]\u001b[0m\n",
      "\n",
      "\u001b[32m============================== \u001b[32m\u001b[1m5 passed\u001b[0m\u001b[32m in 0.01s\u001b[0m\u001b[32m ===============================\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "!pytest tests/test_engine.py::EngineTests"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[1m============================= test session starts ==============================\u001b[0m\n",
      "platform darwin -- Python 3.10.8, pytest-7.2.0, pluggy-1.0.0\n",
      "rootdir: /Users/alexander.ignatov/Documents/PythonCourse2022/15 - Testing\n",
      "collected 1 item                                                               \u001b[0m\n",
      "\n",
      "tests/test_engine.py \u001b[32m.\u001b[0m\u001b[32m                                                   [100%]\u001b[0m\n",
      "\n",
      "\u001b[32m============================== \u001b[32m\u001b[1m1 passed\u001b[0m\u001b[32m in 0.00s\u001b[0m\u001b[32m ===============================\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "!pytest tests/test_engine.py::EngineTests::test_initialWord_isMaskedCorrectly"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "По-подробна употрвба, като изпълнение на тестове по маркери, такива от пакети и т.н. може да видите в [документацията на pytest](https://docs.pytest.org/en/7.1.x/how-to/usage.html)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Добри практики"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Файлова структура"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Модулът/пакетът с тестови код трябва да е отделен от пакетите, съдържащи основния код. Това е за да се избегне циклична зависимост между тях (зависимостта трябва да е в едната посока само - тестовете зависят от основния код, но той от тях - не). Това означава, че трябва да има две отделни директории - една с основния код, друга с тестовете:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[01;34mgame\u001b[0m\n",
      "├── \u001b[00mengine.py\u001b[0m\n",
      "├── \u001b[00mlevel.py\u001b[0m\n",
      "├── \u001b[00mplayer.py\u001b[0m\n",
      "└── \u001b[01;34mplayers\u001b[0m\n",
      "    ├── \u001b[00mai.py\u001b[0m\n",
      "    └── \u001b[00minput_player.py\u001b[0m\n",
      "\u001b[01;34mtests\u001b[0m\n",
      "├── \u001b[00m__init__.py\u001b[0m\n",
      "├── \u001b[01;34mmocks\u001b[0m\n",
      "│   ├── \u001b[00m__init__.py\u001b[0m\n",
      "│   └── \u001b[00mmock_player.py\u001b[0m\n",
      "├── \u001b[00mtest_ai_player.py\u001b[0m\n",
      "└── \u001b[00mtest_engine.py\u001b[0m\n",
      "\n",
      "1 directory, 5 files\n"
     ]
    }
   ],
   "source": [
    "!tree game tests"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В случай, че имаме и unit, и integration тестове например, е добре да ги разделим (за да може лесно да изпълняваме само unit тестовете например):"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "project/\n",
    "│\n",
    "├── my_app/\n",
    "│   ├── __init__.py\n",
    "│   ├── component1.py\n",
    "│   └── component2.py\n",
    "│\n",
    "└── tests/\n",
    "    |\n",
    "    ├── unit/\n",
    "    |   ├── __init__.py\n",
    "    |   ├── test_component1.py\n",
    "    |   └── test_component2.py\n",
    "    |\n",
    "    └── integration/\n",
    "        ├── __init__.py\n",
    "        └── test_components_integration.py\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Конвенции за име"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Хубаво е всички файлове и функции/методи с тестови код да започват името си с `test`, за да бъдат автоматично разпознавани от всички test runner-и. Файловете трябва да съдържат името на компонента (или нещо, което не е двусмислено и подсказва кой е въпросния компонент), както и евентуално и тази част от функционалността, която се тества (в случай, че повече от един файл се занимават с един и същ компонент). В нашия случай `test_engine.py` или `test_BesenitsaEngine.py` биха били добри имена.\n",
    "\n",
    "Името на един тест e хубаво да подсказва какво се тества, какво се очаква и евентуални при какви специфични условия (например `test_initial_word_is_masked_correctly` или разделено семантично чрез комбинация от snake_case и camelCase като `test_initialWord_isMaskedCorrectly`). Съществува практика и за номерирането на тестовете (т.е. `test_001_initialWord_isMaskedCorrectly`). Силно препоръчително е всеки тест да си има docstring с описание на тестовия сценарий. \n",
    "\n",
    "Имената на допълнителните класове/функции, създадени специално за тестовете, е хубаво да подсказват каква е ролята им в тестовете - дали са fixtures, helpers, stubs, mocks, spies и т.н."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Arrange-Act-Assert\n",
    "\n",
    "Тази схема ни помага да структурираме по-нагледно съдържанието на един тест. Тя ни казва да разделим кода в един тестови случай на три последователни части:\n",
    "\n",
    "* Arrange - инстанциране на обекта, който ще се тества, подготовка на данните (fixtures), нагласяне на mock-ове, инжектиране на зависимости (dependency injection) и т.н.\n",
    "* Act - действието, което всъщност тестваме (най-често представлява просто извикване на метода/методите от обекта, който/които ще се тества/тестват)\n",
    "* Assert - проверки"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Например в `EngineTests` имаме следните тестове:\n",
    "\n",
    "```python\n",
    "# ...\n",
    "\n",
    "class EngineTests(unittest.TestCase):\n",
    "    def test_initialWord_isMaskedCorrectly(self):\n",
    "        # Arrange\n",
    "        player = MockPlayer(1, \"a\")\n",
    "        sut = BesenitsaEngine(\"cat\", player)\n",
    "        expected = \"C_T\"\n",
    "\n",
    "        # Act\n",
    "        result = sut.masked_word\n",
    "\n",
    "        # Assert\n",
    "        self.assertEqual(result, expected)\n",
    "    \n",
    "    def test_cat_win(self):\n",
    "        # Arrange\n",
    "        player_win = MockPlayer(1, \"a\")\n",
    "        sut = BesenitsaEngine(\"cat\", player_win)\n",
    "\n",
    "        # Act\n",
    "        result = sut.guess()\n",
    "\n",
    "        # Assert\n",
    "        self.assertEqual(result, GameState.WON)\n",
    "\n",
    "    def test_cat_lose(self):\n",
    "        # Arrange\n",
    "        player_win = MockPlayer(1, \"b\")\n",
    "        sut = BesenitsaEngine(\"cat\", player_win)\n",
    "\n",
    "        # Act\n",
    "        result = sut.guess()\n",
    "\n",
    "        # Assert\n",
    "        self.assertEqual(result, GameState.LOST)\n",
    "    \n",
    "    # ...\n",
    "```\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`sut` идва от `System Under Test` - това е обекта, който се тества в текущия unit test)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Изпълнение от IDE/editors"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### PyCharm\n",
    "\n",
    "1. В Project tool избираме тестовата директория\n",
    "2. В контекстното ѝ меню избираме съответната run команда.\n",
    "\n",
    "![pycharm](assets/pycharm.png)\n",
    "\n",
    "Повече инфо (в сайта на PyCharm)[https://www.jetbrains.com/help/pycharm/performing-tests.html]."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### VS Code\n",
    "\n",
    "Плъгина [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) има команди свързани с тестовете, като \"Debug all unit tests\", \"Run all unit tests\", и т.н.:\n",
    "\n",
    "![vscode](assets/vscode-python.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "При първото изпълнение на такава команда VS Code ще помогне да се настроят накои параметри за изпълнението на тестовете (unittest vs pytest, директория, т.н.), които ще запамети като настройки.\n",
    "\n",
    "След това резултатът от тестовете ще се показва долу вляво в информационната лента:\n",
    "\n",
    "![vscode status](assets/vscode-bottom.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Съществуват и плъгините [Text Explorer UI](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-test-explorer) и [Python Test Explorer](https://marketplace.visualstudio.com/items?itemName=LittleFoxTeam.vscode-python-test-adapter), които показва тестовете в ново меню (в лентата, която обикновено седи в лявата част на екрана):\n",
    "\n",
    "![vscode test ui](assets/vscode-testui.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Както се вижда, добавя UI за изпълнението или дебъгването на конкретен тест или цял набор от тестове. Покачва до дефиницията на всеки тест дали последно е минал успешно или не, и ако не - показва грешката, която е хвърлил."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.8"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "575a2390037550e0ddfbbe541bd43473f612bd2737db9cbfb767783f6b7ec1c8"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}