Skip to content

manual-testing.md

Latest commit

 

History

History
202 lines (151 loc) · 12.8 KB

manual-testing.md

File metadata and controls

202 lines (151 loc) · 12.8 KB
Raw

Ручной чек-лист тестирования

Этот документ покрывает то, что принципиально не берётся автотестами: живой TUI, реальное развёртывание контейнера и онбординг на настоящем проекте. Пройти по каждому пункту вживую и отметить результат: [ ] → [x].

1. TUI-навигатор

Запуск: docker compose exec memory cms (без аргументов).

Запуск и список

  • Команда без аргументов открывает TUI — виден список «All notes».
  • ↑/↓ двигают курсор по списку.
  • q выходит из TUI, терминал не сломан (raw-mode восстановлен).

Разворот заметки

  • Enter на строке списка открывает detail-вид: тело заметки, карта якорей (сгруппирована по весам), блок упомянутых заметок [[id]].
  • Esc (или Backspace) из detail возвращает в список, курсор на той же позиции.

Переход по [[id]]

  • В detail встать на строку-упоминание ([[id]]), Enter — открылась связанная заметка.
  • На stale-упоминании Enter не переходит (заметка-цель удалена или id изменён).

Переход по якорю

  • В detail встать на строку якоря entity:…, Enter — список «Anchor: entity:…» с заметками, привязанными к этому якорю.
  • Аналогично для якоря file:….
  • Аналогично для якоря symbol:….

Поиск изнутри

  • / открывает строку ввода Search.
  • Ввод символов — строка накапливается; Backspace/Delete — стирает.
  • Enter с непустым запросом — переход в список «Search: <запрос>».
  • Enter с пустой строкой — поиск не выполняется, остаёмся на месте.
  • Esc в режиме ввода — отмена, возврат к предыдущему виду без поиска.

Toggle драфтов и архива (d / a)

  • В виде «Search: …» или «Anchor: …» по умолчанию draft/outdated скрыты; строка подсказок показывает d: drafts off a: archived off.
  • d — в выдаче появляются draft-заметки, подсказка drafts on; повторное d — скрывает обратно.
  • a — то же для outdated-заметок.
  • В списке «All notes» draft/outdated видны всегда, toggle-подсказки нет, d/a ничего не меняют.

История переходов (назад)

  • После цепочки переходов (список → заметка → якорь → заметка) Esc/Backspace последовательно возвращает по кадрам до стартового списка.
  • Forward-навигации нет — это нормально.

e — редактирование

  • В detail e открывает .md-файл заметки в $EDITOR.
  • После выхода из редактора экран перерисован, правки видны (reconcile отработал автоматически).
  • Если $EDITOR не найден (или не задан и vi недоступен) — красная строка editor "<name>" not found; set $EDITOR, TUI продолжает работу.

d — удаление

  • В detail d переводит в режим подтверждения: подсказка y: confirm n/Esc: cancel.
  • y (или Y) — заметка удалена, TUI уходит на кадр назад, список обновлён.
  • n или Esc — отмена, заметка осталась.

2. Развёртывание контейнера + dogfooding с Claude Code

Сборка и запуск

  • Собрать образ из Dockerfile: 
    docker build -t code-memory-service .
# или через docker compose build memory
  • Добавить блок service: memory в docker-compose.yml целевого проекта: 
    memory:
  build: ../code-memory-service   # путь к клону этого репозитория
  environment:
    CMS_PROJECT_ROOT: /project
    CMS_PORT: 8765
  volumes:
    - .:/project:ro
    - ./.memory:/project/.memory:rw
  restart: unless-stopped
  • docker compose up -d memory — контейнер поднялся.
  • В логах (docker compose logs memory) видно, что на старте сервис сверил content hash файлов и переиндексировал расхождения.
  • docker compose exec memory cms stats — CLI внутри контейнера отвечает, показывает статистику индекса.

Подключение Claude Code

  • Добавить .mcp.json в корень целевого проекта: 
    {
  "mcpServers": {
    "code-memory": {
      "type": "http",
      "url": "http://memory:8765/mcp"
    }
  }
}
    (или командой claude mcp add --transport http --scope project code-memory http://memory:8765/mcp)
  • Убедиться, что Claude Code запущен в той же compose-сети, что и контейнер memory — обращение идёт по имени сервиса.

Цикл вживую

  • create_note из Claude Code — заметка создалась (id возвращён).
  • search находит только что созданную заметку по тексту или якорю.
  • get_notes([id]) разворачивает заметку: тело, карта якорей, блок [[id]].
  • Изменить файл кода в целевом проекте → повторить search/ docker compose exec memory cms verify → индекс отражает свежее состояние (watcher переиндексировал изменение).

3. Онбординг на реальном проекте

Флоу по specs/06-onboarding.md. Применяется при подключении сервиса к уже существующему проекту.

Фаза 1 — Бутстрап

  • На пустом .memory/ reindex строит symbol_index через tree-sitter. (Запускается автоматически на старте сервиса; можно явно: cms reindex --code.)
  • cms stats показывает непустой symbol_index.

Фаза 2 — Setup

  • Объяснить Клоду логику преобразования: где лежат источники, как сырьё отображается в заметки (пример: «спеки в docs/, секция уровня ## = одна заметка»).
  • Клод предлагает кандидатов доменных сущностей из структуры кода; человек прорежает список.
  • Одобренные сущности зарегистрированы через create_entity.
  • list_entities возвращает реестр с ожидаемыми сущностями.

Фаза 3 — Цикл по чанкам

  • Документация скормлена частями; для каждого чанка Клод делает search с include_drafts: true перед create_note — draft-заметки прошлых чанков находятся, дубликаты сливаются через update_note, не дублируются.
  • Новые заметки создаются со status: draft.
  • Сырой текст чанка сброшен перед переходом к следующему.
  • .memory/onboarding.md ведётся: план, правила преобразования, чек-лист источников (обработано / в очереди / пропущено).

Многосессионность

  • Онбординг прерван и возобновлён в новой сессии: .memory/onboarding.md прочитан, прогресс восстановлен, работа продолжена с нужного места.

Фаза 4 — Review

  • draft-заметки просмотрены; корректные промотированы в current через update_note({status: "current"}).
  • Некорректные или лишние остаются draft или удаляются.
  • По завершении .memory/onboarding.md удалён или помечен архивным.

Нечёткие источники

  • На источнике без явного намерения документировать (тесты, миграции, общая документация) заметка создаётся только при проверяемом артефакте-источнике (существование символа — по индексу, инвариант теста — по имени).
  • «Почему так» без явного источника не реконструируется. При неуверенности используется investigation-форма тела с явными метками Подтверждено / Гипотезы.

4. Непокрытые допущения — что замерить вживую

Допущения, которые нельзя проверить автотестами. Для каждого — заполнить колонку Результат после вживого прогона.

Допущение Где в коде Что замерить Результат
Parser.init() в Docker — WASM-движок tree-sitter и грамматики грузятся из tree-sitter-wasms/.../out/*.wasm; путь строится через createRequire structural-indexer.ts:108-126 Внутри образа node:24: запустить cms reindex --code и проверить, что символы проиндексированы. Если ошибка — вероятно, нужен locateFile для движкового web-tree-sitter.wasm
BM25_FLOOR = 1e-9 — релевантность ниже порога = не матч; на маленьком корпусе порог не задействован search.ts:13, 130 На корпусе ≥50 заметок: ищет ли сервис по общим словам (не отсекает ли валидные слабые матчи); нет ли мусора в топе
UBIQUITY_RATIO = 0.7, MIN_CORPUS_FOR_IDF = 5 — якорь, встречающийся у ≥70% заметок при корпусе ≥5, не даёт IDF-вклада search.ts:8-9, 109 На реальном корпусе: есть ли «вездесущие» якоря, которые не должны быть вездесущими? Снизить UBIQUITY_RATIO до 0.5 если поиск по якорю даёт странные результаты
$EDITOR в Docker-образе и в TUI — дефолт vi; TUI снимает raw-mode через setRawMode(false) и восстанавливает после editor.ts:6, app.tsx:186-193 Есть ли vi в node:24? (docker compose exec memory which vi). Не «зависает» ли терминал после выхода из редактора (raw-mode не вернулся)
reconcileStructure на каждый CLI-вызов — структурный реиндекс на каждый холодный старт CLI context.ts (reconcile) Замерить time docker compose exec memory cms stats на репозитории с 1000+ файлами. Если >2s — задержка заметна

Документ обновляется по результатам прогона. После полного прохода пункты отмечены [x], колонка «Результат» заполнена.