Files
clean-architecture-backend-…/scripts/tests/test_verify_httpclient_docs.py
DongHyeonka ea25f624b2
pr / done (pull_request) Canceled after 0s
fix(scripts)!: httpclient 문서 검사가 설정 필드를 절과 표 위치로 대조한다
verify-httpclient-docs.py는 manifest 필드를 마지막 마디로 줄이고
(clients[N].tls.enabled → enabled) 아홉 문서를 이은 글에서 부분 문자열로
찾는다. 마지막 마디가 겹치는 이름이 여섯 종(enabled 셋, name, type,
protocols, allowed-hosts, allowed-ports)이라 그 이름의 새 필드는 문서 없이
통과한다. 「지운 설정」 표에만 적힌 key도 통과한다. 다섯 종류 추출 어느
것도 0개를 실패로 보지 않고, transport 정규식은 숫자를 빼서 HTTP3 꼴
상수를 뽑지 못한다.

설정 필드는 configuration-reference.md의 속성 표(머리 첫 칸 「속성」)를
제목과 첫 칸으로 읽어(documented_properties) 전체 경로로 대조한다. ##
제목의 app.httpclient.<block>이 블록, ### 제목의 코드 표기가 묶음이다.
지운 key 표·설명 표와 코드 블록 안 표는 세지 않는다. manifest 필드는 끝
[N]·[M]만 뗀다. 종류마다 0개면 실패하고, transport 정규식에 숫자를
넣었다. 이 대조로 처음 드러난 최상위 rotation-drain-timeout 행을 설정
참조에 더했다. 버린 안: 마지막 두 마디 대조. 표가 절 아래 leaf만 적어서
51개 필드의 두 마디가 문서에 같이 나오지 않아, 문서 표 형식부터 바꿔야
했다.

위험: 설정 필드는 이제 configuration-reference.md 속성 표에 있어야 한다.
다른 여덟 문서에만 있으면 실패다. 나머지 네 종류는 전처럼 부분 문자열로
찾는다. 실제 트리 대조는 여전히 release job에서만 돈다. 시험은 고정
설정 참조와 manifest를 써서 실제 트리에 필드를 더해도 빨개지지 않는다.

검증: 새 시험을 main 판 검사기에 얹어 FAIL 4·ERROR 1(새 필드·속성 표
밖 key·빈 manifest·숫자 transport가 rc=0으로 통과, 파서 시험은 함수
없음). 고친 뒤 python3 -m unittest discover -s scripts/tests OK(313),
python3 scripts/verify-httpclient-docs.py rc=0(설정 필드 74, 문서 쪽
남는 경로 0), 검사기 변이 15개 중 14개를 시험이 잡고 1개는 등가,
check-docs.py·check-work-docs.py rc=0.

Refs: REV-BE-0013
BREAKING CHANGE: app.httpclient 필드를 더한 파생 서비스는 그 필드를
  configuration-reference.md의 자기 절 속성 표에 적어야 release 문서
  검사를 통과한다. docs/upgrade/2026-11-httpclient-docs-check.md를 본다.
2026-11-22 03:11:04 +09:00

268 lines
9.0 KiB
Python

"""scripts/verify-httpclient-docs.py의 시험. 코드의 이름이 문서에서 빠지면 실패하는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import io
import sys
import tempfile
import unittest
from contextlib import redirect_stdout
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("verify_httpclient_docs", SCRIPTS / "verify-httpclient-docs.py")
verify_httpclient_docs = importlib.util.module_from_spec(_spec)
sys.modules["verify_httpclient_docs"] = verify_httpclient_docs
_spec.loader.exec_module(verify_httpclient_docs)
# A configuration reference shaped like the real one: property tables (header `속성`) under block
# and group headings, plus a removed-key table and an explanatory table that name settings without
# documenting them. The cases below use it instead of the real reference, so a service that adds and
# documents `clients[N].tls.enabled` does not turn them red.
REFERENCE = """\
## `app.httpclient.clients[N]`
| 속성 | 타입 | 기본값 | 비고 |
|---|---|---|---|
| `allowed-hosts` | list | 비어 있음 | |
### 지운 설정
| 지운 key | 이유 |
|---|---|
| `timeout.request-write-idle` | |
| `app.httpclient.clients[N].timeout.proxy-connect` | |
### `circuit-breaker`
| 끝낸 것 | Breaker | 이유 |
|---|---|---|
| `total-call` | 실패로 기록한다 | |
### `redirect`, `request`, `response`
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `redirect.enabled` | `false` | |
### `tls`
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `profile-id` | — | |
### `proxy`와 `observability`
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `proxy.enabled` | `false` | |
"""
def run_main() -> tuple[int, str]:
output = io.StringIO()
with redirect_stdout(output):
rc = verify_httpclient_docs.main()
return rc, output.getvalue()
class HttpclientDocsTest(unittest.TestCase):
# No case runs the verifier over the real tree and expects 0: that is the release workflow's
# check, and this suite runs in the pull-request gate (documentCheck).
def setUp(self) -> None:
self._workdir = tempfile.TemporaryDirectory()
self.workdir = Path(self._workdir.name)
self._saved = {
name: getattr(verify_httpclient_docs, name)
for name in ("ENV_FIELD_MANIFEST", "TRANSPORT_TYPE", "read_docs", "read_configuration_reference")
if hasattr(verify_httpclient_docs, name)
}
def tearDown(self) -> None:
for name, value in self._saved.items():
setattr(verify_httpclient_docs, name, value)
self._workdir.cleanup()
def use_manifest(self, *fields: str) -> None:
manifest = self.workdir / "env-fields.yaml"
entries = "".join(f" - field: {field}\n env: APP_HTTPCLIENT_TEST_ONLY\n" for field in fields)
manifest.write_text("fields:\n" + entries, encoding="utf-8")
verify_httpclient_docs.ENV_FIELD_MANIFEST = manifest
def use_reference(self, text: str) -> None:
# The reference also joins the documentation the other kinds are searched in, as the real
# one does.
read_docs = self._saved["read_docs"]
verify_httpclient_docs.read_docs = lambda: read_docs() + "\n" + text
verify_httpclient_docs.read_configuration_reference = lambda: text
def test_a_metric_missing_from_the_documentation_fails_naming_it(self) -> None:
# given
metric = verify_httpclient_docs.metric_names()[0]
original = verify_httpclient_docs.read_docs
verify_httpclient_docs.read_docs = lambda: original().replace(metric, "")
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
self.assertIn(f"metric '{metric}'", output)
def test_a_new_field_whose_leaf_is_documented_in_another_section_fails_naming_its_path(self) -> None:
# given: `enabled` is documented, but under redirect and proxy, not under tls
self.use_reference(REFERENCE)
self.use_manifest("clients[N].redirect.enabled", "clients[N].proxy.enabled", "clients[N].tls.enabled")
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
self.assertIn("configuration property 'clients[N].tls.enabled'", output)
self.assertNotIn("'clients[N].redirect.enabled'", output)
self.assertNotIn("'clients[N].proxy.enabled'", output)
def test_a_new_field_documented_under_its_section_is_not_reported(self) -> None:
# given
row = "| `profile-id` | — | |\n"
self.assertIn(row, REFERENCE)
self.use_reference(REFERENCE.replace(row, row + "| `enabled` | `true` | |\n"))
self.use_manifest("clients[N].redirect.enabled", "clients[N].proxy.enabled", "clients[N].tls.enabled")
# when
_, output = run_main()
# then
self.assertNotIn("configuration property '", output)
def test_a_field_named_only_outside_a_property_table_fails(self) -> None:
# given: the removed-key table and the circuit-breaker table name these, no property table does
self.use_reference(REFERENCE)
fields = (
"clients[N].timeout.request-write-idle",
"clients[N].timeout.proxy-connect",
"clients[N].circuit-breaker.total-call",
)
self.use_manifest(*fields)
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
for field in fields:
self.assertIn(f"configuration property '{field}'", output)
def test_a_list_field_is_matched_by_its_name_without_the_index(self) -> None:
# given
self.use_reference(REFERENCE)
self.use_manifest("clients[N].allowed-hosts[M]")
# when
_, output = run_main()
# then
self.assertNotIn("configuration property '", output)
def test_the_reference_is_read_by_block_and_group_from_property_tables_only(self) -> None:
# given
reference = "\n".join(
[
"# 설정",
"## 주 스위치",
"| 속성 | 타입 |",
"|---|---|",
"| `app.httpclient.enabled` | boolean |",
"## `app.httpclient.clients[N]`",
"| 속성 | 타입 | 비고 |",
"|---|---|---|",
"| `name` | string | `app.httpclient.in-another-cell` |",
"```yaml",
"| 속성 | x |",
"|---|---|",
"| `fenced` | x |",
"```",
"### `pool`",
"| 속성 | 기본값 |",
"|---|---|",
"| `max-idle-time` | `30s` |",
"| `pool.max-life-time` | `5m` |",
"",
"| 끝낸 것 | 이유 |",
"|---|---|",
"| `explained` | not a property table |",
"### `redirect`, `request`",
"| 속성 | 기본값 |",
"|---|---|",
"| `redirect.enabled` | `false` |",
"| `timeout.dns` | not a group this heading names |",
"| `bare` | ambiguous under two groups |",
"### 지운 설정",
"| 지운 key | 이유 |",
"|---|---|",
"| `app.httpclient.clients[N].timeout.request-write-idle` | removed |",
"## 시작 위반 코드",
"| 속성 | x |",
"|---|---|",
"| `top-level` | x |",
"## `app.httpclient.dynamic-targets[N]`",
"| 속성 | 기본값 |",
"|---|---|",
"| `name` | — |",
]
)
# when
documented = verify_httpclient_docs.documented_properties(reference)
# then
self.assertEqual(
documented,
{
"enabled",
"clients[N].name",
"clients[N].pool.max-idle-time",
"clients[N].pool.max-life-time",
"clients[N].redirect.enabled",
"top-level",
"dynamic-targets[N].name",
},
)
def test_a_manifest_with_no_field_fails_instead_of_checking_nothing(self) -> None:
# given
self.use_manifest()
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
self.assertIn("no configuration property", output)
def test_a_transport_constant_with_a_digit_is_checked(self) -> None:
# given
transport_type = self.workdir / "TransportType.java"
transport_type.write_text(
"package x;\n\npublic enum TransportType {\n APACHE,\n QUIC2\n}\n", encoding="utf-8"
)
verify_httpclient_docs.TRANSPORT_TYPE = transport_type
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
self.assertIn("transport 'QUIC2'", output)
if __name__ == "__main__":
unittest.main()