How to write compat tests

ydb/tests/compatibility/README.md

@@ -1,56 +1,72 @@
-# Тесты совместимости 
+# Тесты совместимости
 
-Одна из мажорных проблем в новых стабильных ветках состоит в том, что в рамках апгрейда YDB со старой версии возникают несовмстимости между новой и старой версией. Данные тесты призваны протестировать этот сценарий. Механика тестов следующая: тесты скачивают YDB последней стабильной версии.
+Тесты совместимости позволяют обнаруживать ошибки, которые возникают при апгрейде и даунгрейде YDB. 
 
-После чего у нас есть два бинарных файла: текущий (собранный из текущего среза сорцов) и предыдущий. Таким образом, в этих тестах можно использовать тестовый кластер не только с одной версией YDB, а с двумя. Текущая версия условно называется **current**, а предыдущая **last**.
+## Механика работы тестов
 
-Для упрощения написания тестов было сделано несколько тестовых фикстур, которые предоставляют типовые сценарии тестирования. Все фикстуры поднимают кластер `MIRROR_3_DC` и предоставляют его для тестирования. 
+Тестовая обвязка скачивает YDB последней стабильной версии. После этого тестам доступны два бинарных файла: текущий (собранный из текущего среза исходников) и предыдущий. Таким образом, в этих тестах можно использовать тестовый кластер не только с одной версией YDB, но и с двумя. Текущая версия условно называется **current**, а предыдущая — **last**.
+
+## Как написать тест
+
+1. Выбрать подходящую [фикстуру](#фикстуры)
+2. Сделать новый файл с тестом (либо же выбрать имеющийся, если он подходит по области)
+3. Закодировать тест. Как первый шаг, можно скопировать пример из [test_example.py](test_example.py)
+
+## Фикстуры
+
+Для упрощения написания тестов было создано несколько тестовых фикстур, которые предоставляют типовые сценарии тестирования. Фикстуры содержат в себе общую логику, которую можно переиспользовать в тестах. Все фикстуры поднимают кластер `MIRROR_3_DC` и предоставляют его для тестирования.
 
 Примеры использования фикстур можно посмотреть в [test_example.py](test_example.py)
 
-## MixedClusterFixture
-Фикстура поднимает кластер который состоит из нод версий current и last. Позволяет протестировать работу в режиме, когда часть нод у нас уже обновилась, а часть еще нет. 
+### MixedClusterFixture
+
+Фикстура поднимает кластер, который состоит из нод версий current и last. Позволяет протестировать работу в режиме, когда часть нод у нас уже обновилась, а часть еще нет.
 
 Имеет параметризацию (то есть каждый написанный такой тест превращается в несколько):
 - поднимается смешанный кластер last+current
 - поднимается кластер исключительно на версии last
 - поднимается кластер исключительно на версии current
 
-Последние два нужны чтобы отвечать на вопрос "а работает ли у такой сценарий в принципе, когда кластер состоит из нод одной вресии". Если получается так, что тест last+current не проходит, а в отсутствие разных версий тест завершается успешно, то это сильный сигнал к тому, что где-то поломана совместимость. 
+Последние два нужны, чтобы отвечать на вопрос "а работает ли такой сценарий в принципе, когда кластер состоит из нод одной версии". Если получается так, что тест last+current не проходит, а в отсутствие разных версий тест завершается успешно, то это сильный сигнал к тому, что где-то поломана совместимость.
+
+#### Для чего использовать
 
-### Для чего использовать
-Для проверки совместимости версий в рамках исполнения запросов, которые требуют взаимодействия между нодами кластера.  
+Для проверки совместимости версий в рамках исполнения запросов, которые требуют взаимодействия между нодами кластера.
 
-## RestartToAnotherVersionFixture
-Фикстура сначала поднимает кластер в одной комбинации (например, все ноды last), а потом позволяет остановить кластер и поднять кластер с другими версиями (например, все ноды current). 
+### RestartToAnotherVersionFixture
+
+Фикстура сначала поднимает кластер в одной комбинации (например, все ноды last), а потом позволяет остановить кластер и поднять кластер с другими версиями (например, все ноды current).
 
 Имеет параметризацию (то есть каждый написанный такой тест превращается в несколько):
-- обновление last -> current
-- обновление current -> last
-- обновление current -> current
+- обновление last → current
+- обновление current → last
+- обновление current → current
+
+Список не исчерпывающий, полный можно посмотреть в коде фикстуры.
+
+В самом тесте для смены версий необходимо вызвать `self.change_cluster_version()`, и версия изменится.
 
-Список не исчерпывающий, полный можно посмотреть в коде фикстуры. 
+#### Для чего использовать
 
-В самом тесте для смены версий необходимо вызвать `self.change_cluster_version()` и версия изменится. 
+Данная фикстура позволяет протестировать, например, несовместимости по данным (как и при апгрейде, так и при даунгрейде), например, что новая версия не пишет чего-то, что старая версия не может прочитать.
 
-### Для чего использовать
-Данная фикстура позволяет протестировать, например, несовместимости по данным (как и при апгрейде, так и при даунгрейде), например, что новая версия не пишет чего-то, что старая версия не может прочитать. 
+### RollingUpgradeAndDowngradeFixture
 
-## RollingUpgradeAndDowngradeFixture
-Фикстура позволяет протестировать сценарий роллинг апгрейда и даунгрейда. Реализует сценарий "имеется кластер last версии, он понодно заменяется на current версию, потом обратно на last". 
+Фикстура позволяет протестировать сценарий роллинг-апгрейда и даунгрейда. Реализует сценарий "имеется кластер last версии, он понодно заменяется на current версию, потом обратно на last".
 
-Сама фикстура сначала поднимает кластер версии last, потом заменяет ноды на версию current, а потом оборатно понодно заменяет на last эмулируя откат. 
+Сама фикстура сначала поднимает кластер версии last, потом заменяет ноды на версию current, а потом обратно понодно заменяет на last, эмулируя откат.
 
-Шаг апгрейда/даунгрейда (замена версии ноды на другую) вызывается из теста следующим образом: 
+Шаг апгрейда/даунгрейда (замена версии ноды на другую) вызывается из теста следующим образом:
 
 ```python
-        for _ in self.roll():
-            pass  # do something with cluster between upgrade/downgrade steps
+for _ in self.roll():
+    pass  # do something with cluster between upgrade/downgrade steps
 ```
 
-На каждой итерации цикла тестовое окружение заменяет одну ноду на другую версию. 
+На каждой итерации цикла тестовое окружение заменяет одну ноду на другую версию.
+
+Схематично можно изобразить следующим образом (L — last, C — current, каждый столбец — это версия ноды кластера, каждая строка — текущее состояние кластера в теле цикла):
 
-Схематично можно изобразить следующим образом (L -- last, C -- current, каждый столбец это версия ноды кластера, каждая строка -- текущее состояние кластера в теле цикла)
 ```
 LLLLLLLLL
 CLLLLLLLL
@@ -65,5 +81,6 @@ LLLLLLLLC
 LLLLLLLLL
 ```
 
-### Для чего использовать
-Это наиболее приблеженный к реальности сценарий. Его, например, можно использовать для тестирования, в котором необходимо чтобы все таблетки со 100% гарантией в рамках работы кластера переехали с одной версии на другую. 
+#### Для чего использовать
+
+Это наиболее приближенный к реальности сценарий. Его, например, можно использовать для тестирования, в котором необходимо, чтобы все таблетки со 100% гарантией в рамках работы кластера переехали с одной версии на другую.