fix(tests): сторож документации называет непрошедшую проверку, кластерная больше не виснет
Зачем. Сторож `tests/docs-guards.sh` падал через `set -e`: единственным следом была единица в коде возврата, а какое именно утверждение о README перестало быть правдой — не сообщалось. Со стороны файл выглядел набором несвязанных grep без объяснения, зачем каждый из них нужен. Отдельно: `make smoke-cluster` мог зависнуть навсегда. У запроса INSERT clickhouse-client дочитывает данные из стандартного ввода и ждёт его конца; при запуске не из терминала, а из фонового процесса с открытым вводом конец не наступает никогда. Проверка молча висела больше двадцати минут. Что. - Проверки собраны в именованные функции, каждая с комментарием, зачем она существует и что ломается, когда она краснеет. - Обёртка `check` печатает утверждение и при успехе, и при провале, считает пройденные и выходит с понятным сообщением. - Ввод запросов ClickHouse закрыт через `</dev/null`, рядом — объяснение причины. - README: раздел «Какую проверку когда запускать» — лесенка от дешёвой статической проверки к дорогой интеграционной, с ответом, зачем внутри `make smoke-guards` три прогона `make smoke`. Проверка. make config-test — пройдено 3, 3 и 6, ошибок 0. Фальсификация сторожа: порт ноды 2 в README изменён — «ОШИБКА: не подтвердилось: README перечисляет HTTP- и нативные порты обеих нод», код 1; двоеточие в строке про перезапуск ClickHouse заменено на тире — «ОШИБКА: не подтвердилось: README требует перезапуск ClickHouse после изменения настройки метрик», код 1. README восстановлен из индекса. make smoke-cluster с открытым стандартным вводом — 8 проверок за 7 с; до починки та же команда висела 23 минуты и была снята вручную. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
+109
-40
@@ -1,48 +1,117 @@
|
||||
#!/usr/bin/env bash
|
||||
# Сторож документации.
|
||||
#
|
||||
# README устаревает молча: порт поменяли в compose.yaml, а в описании остался
|
||||
# старый — и это выясняется через месяц, когда кто-то по нему подключается.
|
||||
# Здесь собраны утверждения README, которые дёшево проверить текстом и дорого
|
||||
# обнаружить сломанными. Стенд поднимать не нужно; запускается в составе
|
||||
# `make config-test`.
|
||||
#
|
||||
# Чего сторож НЕ делает: он не проверяет, что README понятен или полон. Только
|
||||
# то, что перечисленные ниже факты не разошлись с кодом.
|
||||
#
|
||||
# Добавляя проверку, формулируй утверждение так, как оно должно читаться в
|
||||
# отчёте: строка печатается и при успехе, и при провале, поэтому по красной
|
||||
# строке сразу видно, что именно перестало быть правдой.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
readonly ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
readonly README="$ROOT_DIR/README.md"
|
||||
readonly SMOKE="$ROOT_DIR/scripts/stand-smoke.sh"
|
||||
passed=0
|
||||
|
||||
grep -Eq 'нода 1.*28123.*29000' "$README"
|
||||
grep -Eq 'нода 2.*28124.*29001' "$README"
|
||||
printf 'ЗЕЛЁНО: README перечисляет HTTP- и нативные порты обеих нод.\n'
|
||||
|
||||
grep -Eq 'После первого запуска.*`make clean`' "$README"
|
||||
printf 'ЗЕЛЁНО: README объясняет сброс томов после смены исходных учётных данных.\n'
|
||||
|
||||
grep -Fxq -- '- нода 2 — `http://127.0.0.1:28124`, нативный порт `29001`;' "$README"
|
||||
printf 'ЗЕЛЁНО: список портов остаётся единым списком.\n'
|
||||
|
||||
awk '
|
||||
previous == "`make config-test` проверяет Compose, синтаксис Bash и Python, малые проверки" &&
|
||||
$0 == "логики пробников и пробельные ошибки в diff без запуска стенда." {
|
||||
found = 1
|
||||
}
|
||||
{previous = $0}
|
||||
END {exit !found}
|
||||
' "$README"
|
||||
printf 'ЗЕЛЁНО: README перечисляет малые проверки пробников в составе config-test.\n'
|
||||
|
||||
awk '
|
||||
previous == "После изменения `infra/clickhouse/config.d/prometheus.xml` выполните" &&
|
||||
$0 == "`docker compose restart clickhouse-01 clickhouse-02`: обычный `make up` не" {
|
||||
found = 1
|
||||
}
|
||||
{previous = $0}
|
||||
END {exit !found}
|
||||
' "$README"
|
||||
printf 'ЗЕЛЁНО: README требует перезапуск ClickHouse после изменения настройки метрик.\n'
|
||||
|
||||
grep_status=0
|
||||
grep -q '3,4 GB' "$ROOT_DIR/scripts/stand-smoke.sh" || grep_status=$?
|
||||
if [[ "$grep_status" -eq 0 ]]; then
|
||||
printf 'ОШИБКА: отчёт проверки использует латинское обозначение GB.\n' >&2
|
||||
fail() {
|
||||
printf 'ОШИБКА: %s\n' "$1" >&2
|
||||
exit 1
|
||||
elif [[ "$grep_status" -ne 1 ]]; then
|
||||
printf 'ОШИБКА: не удалось проверить обозначение единицы памяти.\n' >&2
|
||||
exit 1
|
||||
fi
|
||||
printf 'ЗЕЛЁНО: отчёт проверки использует русское обозначение ГБ.\n'
|
||||
}
|
||||
|
||||
printf 'ИТОГ: пройдено 6, ошибок 0\n'
|
||||
# check «утверждение» команда... — запускает команду и считает результат.
|
||||
# Успех: «ЗЕЛЁНО: утверждение». Провал: «ОШИБКА: не подтвердилось: утверждение»
|
||||
# и выход с кодом 1. Раньше проверки падали через `set -e` молча: код возврата
|
||||
# был единственным следом, и какая именно проверка не прошла — не сообщалось.
|
||||
check() {
|
||||
local claim="$1"
|
||||
shift
|
||||
if "$@"; then
|
||||
passed=$((passed + 1))
|
||||
printf 'ЗЕЛЁНО: %s\n' "$claim"
|
||||
else
|
||||
fail "не подтвердилось: $claim"
|
||||
fi
|
||||
}
|
||||
|
||||
# Порты обеих нод. Ломается ровно тогда, когда порт поменяли в compose.yaml и
|
||||
# забыли документацию — самая частая причина расхождения.
|
||||
ports_documented() {
|
||||
grep -Eq 'нода 1.*28123.*29000' "$README" &&
|
||||
grep -Eq 'нода 2.*28124.*29001' "$README"
|
||||
}
|
||||
|
||||
# Совет про сброс томов. Пароли Postgres и Grafana применяются при создании
|
||||
# тома: без `make clean` смена значений в .env ничего не даёт, и человек
|
||||
# полчаса ищет, почему его не пускает.
|
||||
clean_advice_present() {
|
||||
grep -Eq 'После первого запуска.*`make clean`' "$README"
|
||||
}
|
||||
|
||||
# Список портов остаётся единым списком. Совпадение точное намеренно: проверка
|
||||
# стережёт не сам факт (он проверен выше), а то, что строку не выдернули из
|
||||
# списка в отдельный абзац при правке соседнего текста.
|
||||
ports_stay_one_list() {
|
||||
grep -Fxq -- '- нода 2 — `http://127.0.0.1:28124`, нативный порт `29001`;' "$README"
|
||||
}
|
||||
|
||||
# Состав `make config-test`. Разбор пробников добавлен в него отдельной
|
||||
# проверкой, и README должен называть её: иначе читатель считает, что дешёвая
|
||||
# ступень трогает только Compose, и гоняет полный стенд ради того, что видно
|
||||
# без него. Проверка стоит на двух соседних строках — см. ниже про перенос.
|
||||
probe_checks_documented() {
|
||||
awk '
|
||||
previous == "`make config-test` проверяет Compose, синтаксис Bash и Python, малые проверки" &&
|
||||
$0 == "логики пробников и пробельные ошибки в diff без запуска стенда." {
|
||||
found = 1
|
||||
}
|
||||
{previous = $0}
|
||||
END {exit !found}
|
||||
' "$README"
|
||||
}
|
||||
|
||||
# Урок из предшественника: `make up` не трогает уже созданные контейнеры, и
|
||||
# после правки настройки метрик серверы молча работают со старой
|
||||
# конфигурацией. README обязан требовать явный перезапуск. Проверка сверяет
|
||||
# две соседние строки целиком, а не подстроку: так фразу нельзя незаметно
|
||||
# разорвать переносом или переписать наполовину.
|
||||
restart_lesson_present() {
|
||||
awk '
|
||||
previous == "После изменения `infra/clickhouse/config.d/prometheus.xml` выполните" &&
|
||||
$0 == "`docker compose restart clickhouse-01 clickhouse-02`: обычный `make up` не" {
|
||||
found = 1
|
||||
}
|
||||
{previous = $0}
|
||||
END {exit !found}
|
||||
' "$README"
|
||||
}
|
||||
|
||||
# Единица памяти в отчёте проверки — русская «ГБ», а не латинская «GB»
|
||||
# (контракт языка из AGENTS.md). Здесь успех — это отсутствие образца, поэтому
|
||||
# код возврата grep разбирается вручную: 1 — не нашли, и это хорошо; 0 — нашли
|
||||
# латинское; больше 1 — сам grep не отработал, и молчать об этом нельзя.
|
||||
smoke_uses_russian_unit() {
|
||||
local status=0
|
||||
grep -q '3,4 GB' "$SMOKE" || status=$?
|
||||
case "$status" in
|
||||
1) return 0 ;;
|
||||
0) return 1 ;;
|
||||
*) fail "не удалось проверить обозначение единицы памяти в $SMOKE" ;;
|
||||
esac
|
||||
}
|
||||
|
||||
check 'README перечисляет HTTP- и нативные порты обеих нод' ports_documented
|
||||
check 'README объясняет сброс томов после смены исходных учётных данных' clean_advice_present
|
||||
check 'список портов остаётся единым списком' ports_stay_one_list
|
||||
check 'README перечисляет малые проверки пробников в составе config-test' probe_checks_documented
|
||||
check 'README требует перезапуск ClickHouse после изменения настройки метрик' restart_lesson_present
|
||||
check 'отчёт проверки использует русское обозначение ГБ' smoke_uses_russian_unit
|
||||
|
||||
printf 'ИТОГ: пройдено %d, ошибок 0\n' "$passed"
|
||||
|
||||
Reference in New Issue
Block a user