Coverage for tests/cli/test_asyncapi_docs.py: 99%
82 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 21:20 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 21:20 +0000
1import json
2from collections.abc import Callable
3from typing import Any, TextIO
5import httpx2
6import pytest
7import yaml
9from tests.cli import interfaces
10from tests.marks import require_aiokafka, skip_macos, skip_windows
12json_asyncapi_doc = """
13{
14 "asyncapi": "2.6.0",
15 "defaultContentType": "application/json",
16 "info": {
17 "title": "FastStream",
18 "version": "0.1.0"
19 },
20 "servers": {
21 "development": {
22 "url": "localhost:9092",
23 "protocol": "kafka",
24 "protocolVersion": "auto"
25 }
26 },
27 "channels": {
28 "input_data:OnInputData": {
29 "servers": [
30 "development"
31 ],
32 "bindings": {
33 "kafka": {
34 "topic": "input_data",
35 "bindingVersion": "0.4.0"
36 }
37 },
38 "subscribe": {
39 "message": {
40 "$ref": "#/components/messages/input_data:OnInputData:Message"
41 }
42 }
43 }
44 },
45 "components": {
46 "messages": {
47 "input_data:OnInputData:Message": {
48 "title": "input_data:OnInputData:Message",
49 "correlationId": {
50 "location": "$message.header#/correlation_id"
51 },
52 "payload": {
53 "$ref": "#/components/schemas/DataBasic"
54 }
55 }
56 },
57 "schemas": {
58 "DataBasic": {
59 "properties": {
60 "data": {
61 "type": "number"
62 }
63 },
64 "required": [
65 "data"
66 ],
67 "title": "DataBasic",
68 "type": "object"
69 }
70 }
71 }
72}
73"""
75yaml_asyncapi_doc = """
76asyncapi: 2.6.0
77defaultContentType: application/json
78info:
79 title: FastStream
80 version: 0.1.0
81 description: ''
82servers:
83 development:
84 url: 'localhost:9092'
85 protocol: kafka
86 protocolVersion: auto
87channels:
88 'input_data:OnInputData':
89 servers:
90 - development
91 bindings: null
92 kafka:
93 topic: input_data
94 bindingVersion: 0.4.0
95 subscribe: null
96 message:
97 $ref: '#/components/messages/input_data:OnInputData:Message'
98components:
99 messages:
100 'input_data:OnInputData:Message':
101 title: 'input_data:OnInputData:Message'
102 correlationId:
103 location: '$message.header#/correlation_id'
104 payload:
105 $ref: '#/components/schemas/DataBasic'
106 schemas:
107 DataBasic:
108 properties:
109 data: null
110 title: Data
111 type: number
112 required:
113 - data
114 title: DataBasic
115 type: object
116"""
119app_code = """
120from pydantic import BaseModel, Field, NonNegativeFloat
122from faststream import FastStream, Logger
123from faststream.specification import AsyncAPI
124from faststream.kafka import KafkaBroker
127class DataBasic(BaseModel):
128 data: NonNegativeFloat = Field(
129 ..., examples=[0.5], description="Float data example"
130 )
133broker = KafkaBroker("localhost:9092")
134app = FastStream(broker, specification=AsyncAPI())
137@broker.publisher("output_data")
138@broker.subscriber("input_data")
139async def on_input_data(msg: DataBasic, logger: Logger) -> DataBasic:
140 logger.info(msg)
141 return DataBasic(data=msg.data + 1.0)
142"""
145@pytest.mark.slow()
146@require_aiokafka
147@skip_windows
148@pytest.mark.parametrize(
149 ("commands", "load_schema"),
150 (
151 pytest.param(
152 [],
153 json.load,
154 id="json",
155 ),
156 pytest.param(
157 ["--yaml"],
158 lambda f: yaml.load(f, Loader=yaml.BaseLoader),
159 id="yaml",
160 ),
161 ),
162)
163def test_gen_asyncapi_for_kafka_app(
164 commands: list[str],
165 generate_template: interfaces.GenerateTemplateFactory,
166 faststream_cli: interfaces.FastStreamCLIFactory,
167 load_schema: Callable[[TextIO], Any],
168) -> None:
169 with (
170 generate_template(app_code) as app_path,
171 faststream_cli(
172 "faststream",
173 "docs",
174 "gen",
175 f"{app_path.stem}:app",
176 "--out",
177 str(app_path.parent / "schema.json"),
178 *commands,
179 ) as cli_thread,
180 ):
181 cli_thread.wait_for_stderr("Your project AsyncAPI scheme")
183 assert cli_thread.process
185 schema_path = app_path.parent / "schema.json"
186 assert schema_path.exists()
188 with schema_path.open() as f:
189 schema = load_schema(f)
191 assert schema
192 schema_path.unlink()
195@pytest.mark.slow()
196@skip_windows
197def test_gen_wrong_path(faststream_cli: Any) -> None:
198 with faststream_cli("faststream", "docs", "gen", "non_existent:app") as cli:
199 assert cli.wait_for_stderr("No such file or directory")
202@skip_windows
203@skip_macos # MacOS GHArunner doesn't allow to run 0.0.0.0 process
204@require_aiokafka
205@pytest.mark.slow()
206@pytest.mark.flaky(reruns=3, reruns_delay=1)
207def test_serve_asyncapi_docs_from_app(
208 generate_template: interfaces.GenerateTemplateFactory,
209 faststream_cli: interfaces.FastStreamCLIFactory,
210) -> None:
211 with (
212 generate_template(app_code) as app_path,
213 faststream_cli(
214 "faststream", "docs", "serve", "--host", "0.0.0.0", f"{app_path.stem}:app"
215 ) as cli,
216 ):
217 cli.wait_for_stderr("Please, do not use it in production.")
219 try:
220 response = httpx2.get("http://0.0.0.0:8000")
221 except Exception as e:
222 raise RuntimeError(cli.stderr) from e
224 assert "<title>FastStream AsyncAPI</title>" in response.text
225 assert response.status_code == 200
228@skip_windows
229@require_aiokafka
230def test_serve_asyncapi_docs_from_app_with_reload(
231 generate_template: interfaces.GenerateTemplateFactory,
232 faststream_cli: interfaces.FastStreamCLIFactory,
233) -> None:
234 with (
235 generate_template(app_code) as app_path,
236 faststream_cli(
237 "faststream",
238 "docs",
239 "serve",
240 f"{app_path.stem}:app",
241 "--reload",
242 ) as cli,
243 ):
244 assert cli.wait_for_stderr("HTTPServer running on http://localhost:8000"), (
245 cli.stderr
246 )
249@skip_windows
250@skip_macos # HTTPServer readiness times out on macOS runners.
251@require_aiokafka
252@pytest.mark.slow()
253@pytest.mark.parametrize(
254 ("doc_filename", "doc"),
255 (
256 pytest.param("asyncapi.json", json_asyncapi_doc, id="json_schema"),
257 pytest.param("asyncapi.yaml", yaml_asyncapi_doc, id="yaml_schema"),
258 ),
259)
260def test_serve_asyncapi_docs_from_file(
261 doc_filename: str,
262 doc: str,
263 generate_template: interfaces.GenerateTemplateFactory,
264 faststream_cli: interfaces.FastStreamCLIFactory,
265) -> None:
266 with (
267 generate_template(doc, filename=doc_filename) as doc_path,
268 faststream_cli(
269 "faststream",
270 "docs",
271 "serve",
272 "--host",
273 "127.0.0.1",
274 str(doc_path),
275 readiness_url="http://127.0.0.1:8000/",
276 ),
277 ):
278 response = httpx2.get("http://127.0.0.1:8000/")
280 assert "<title>FastStream AsyncAPI</title>" in response.text
281 assert response.status_code == 200
284@skip_windows
285def test_serve_asyncapi_yaml_unquoted_scalar_reports_hint(
286 generate_template: interfaces.GenerateTemplateFactory,
287 faststream_cli: interfaces.FastStreamCLIFactory,
288) -> None:
289 """Regression for #2709: the exact reproduction from the issue.
291 `protocolVersion: ! "3.2"` should round-trip to the string `"3.2"` per the YAML
292 1.2 failsafe schema, but PyYAML coerces it to a float that fails AsyncAPI
293 validation. The CLI must surface the per-version validation errors and hint
294 that the value should be quoted.
295 """
296 bad_doc = yaml_asyncapi_doc.replace(
297 "protocolVersion: auto",
298 'protocolVersion: ! "3.2"',
299 )
300 with (
301 generate_template(bad_doc, filename="asyncapi.yaml") as doc_path,
302 faststream_cli("faststream", "docs", "serve", str(doc_path)) as cli,
303 ):
304 cli.wait_for_stderr("not supported", timeout=5.0)
305 cli.wait(timeout=5.0)
307 stderr = cli.stderr
308 assert cli.process is not None
309 assert cli.process.returncode == 1, stderr
310 assert "AsyncAPI v3.0 validation errors" in stderr, stderr
311 assert "AsyncAPI v2.6 validation errors" in stderr, stderr
312 assert "Hint: YAML parses bare `3.2`" in stderr, stderr
313 # The hint must appear exactly once, not once per AsyncAPI version.
314 assert stderr.count("Hint: YAML parses") == 1, stderr
317@skip_windows
318def test_serve_asyncapi_json_numeric_scalar_omits_yaml_hint(
319 generate_template: interfaces.GenerateTemplateFactory,
320 faststream_cli: interfaces.FastStreamCLIFactory,
321) -> None:
322 """The YAML-specific quoting hint must not appear for `.json` inputs.
324 A numeric scalar in a JSON document is a genuine schema error, not a PyYAML
325 coercion, so the hint would only mislead there.
326 """
327 bad_doc = json_asyncapi_doc.replace(
328 '"protocolVersion": "auto"',
329 '"protocolVersion": 3.2',
330 )
331 with (
332 generate_template(bad_doc, filename="asyncapi.json") as doc_path,
333 faststream_cli("faststream", "docs", "serve", str(doc_path)) as cli,
334 ):
335 cli.wait_for_stderr("not supported", timeout=5.0)
336 cli.wait(timeout=5.0)
338 stderr = cli.stderr
339 assert cli.process is not None
340 assert cli.process.returncode == 1, stderr
341 assert "Hint: YAML parses" not in stderr, stderr
344@skip_windows
345def test_serve_asyncapi_reports_yaml_parse_error(
346 generate_template: interfaces.GenerateTemplateFactory,
347 faststream_cli: interfaces.FastStreamCLIFactory,
348) -> None:
349 """Regression for #2709: malformed YAML surfaces the parser's error.
351 A syntactically invalid document should report the parse failure directly
352 instead of failing silently.
353 """
354 bad_yaml = "asyncapi: 2.6.0\nfoo: [unclosed\n"
355 with (
356 generate_template(bad_yaml, filename="asyncapi.yaml") as doc_path,
357 faststream_cli("faststream", "docs", "serve", str(doc_path)) as cli,
358 ):
359 cli.wait_for_stderr("Failed to parse YAML file", timeout=5.0)
360 cli.wait(timeout=5.0)
362 stderr = cli.stderr
363 assert cli.process is not None
364 assert cli.process.returncode == 1, stderr
365 assert "Failed to parse YAML file" in stderr, stderr