Skip to content

Commit 5ffbe8a

Browse files
pekkaklarckpekkaklarck
committed
Libdoc: Enhance docstring parsing tests.
Includes tests for: - parsing docstring - saving results to XML and JSON specs using both HTML and RAW docs - parsing XML and JSON specs Part if robotframework#5604.
1 parent e2cfc6c commit 5ffbe8a

3 files changed

Lines changed: 201 additions & 45 deletions

File tree

‎atest/robot/libdoc/doc_string.robot‎

Lines changed: 153 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,157 @@
11
*** Settings ***
2-
Suite Setup Run Libdoc And Parse Model From JSON ${TESTDATADIR}/DocStringParsing.py
32
Resource libdoc_resource.robot
43

4+
*** Variables ***
5+
${LIBRARY} ${TESTDATADIR}/DocStringParsing.py
6+
${INXML} ${OUTBASE}-2.xml
7+
${INJSON} ${OUTBASE}-2.json
8+
59
*** Test Cases ***
6-
Keyword Doc
7-
Should Be Equal Multiline ${MODEL}[keywords][0][doc] <p>Keyword with different argument and docstring.</p>
8-
... <p>This is second paragraph.</p>
9-
... <p>Here is more text in the docstring after the argument.</p>
10-
... <p>This ends the docstring.</p>
11-
12-
Keyword Arguments Doc
13-
Should Be Equal Multiline ${MODEL}[keywords][0][args][0][doc] <p>Documentation at same line</p>
14-
Should Be Empty ${MODEL}[keywords][0][args][1][doc]
15-
Should Be Equal Multiline ${MODEL}[keywords][0][args][2][doc] <p>With a long description that spans multiple lines</p>
16-
... <p>def keyword(arg, *, kwonly, **kwargs) -&gt; str: pass</p>
17-
Should Be Equal Multiline ${MODEL}[keywords][0][args][3][doc] <p>Documentation at next line</p>
18-
19-
Keyword Return Doc
20-
Should Be Equal Multiline ${MODEL}[keywords][0][returnDoc] <p>This documentation for the return value</p>
21-
22-
Keyword Doc Not Existing Args Doc
23-
Should Be Equal Multiline ${MODEL}[keywords][1][doc] <p><b>Creating keyword failed:</b> Documentation given to non-existing argument 'does_not_exist'.</p>
24-
25-
Keyword Doc Not Existing Args Arguments Doc
26-
Should Be Empty ${MODEL}[keywords][1][args][0][doc]
27-
Should Be Empty ${MODEL}[keywords][1][args][1][doc]
10+
Python to XML with HTML docs
11+
Run Libdoc And Parse Output --spec-doc-format HTML ${LIBRARY}
12+
Validate XML Spec With HTML Docs
13+
14+
Python to XML with raw docs
15+
Run Libdoc And Parse Output ${LIBRARY}
16+
Validate XML Spec With Raw Docs
17+
[Teardown] Copy File ${OUTXML} ${INXML}
18+
19+
XML as input
20+
[Setup] File Should Exist ${INXML}
21+
Run Libdoc And Parse Output ${INXML}
22+
Validate XML Spec With Raw Docs
23+
24+
Python to JSON with HTML docs
25+
Run Libdoc And Parse Model From JSON ${LIBRARY}
26+
Validate JSON Spec With HTML Docs
27+
28+
Python to JSON with raw docs
29+
Run Libdoc And Parse Model From JSON --spec-doc-format RAW ${LIBRARY}
30+
Validate JSON Spec With Raw Docs
31+
[Teardown] Copy File ${OUTJSON} ${INJSON}
32+
33+
JSON as input
34+
[Setup] File Should Exist ${INJSON}
35+
Run Libdoc And Parse Model From JSON ${INJSON}
36+
Validate JSON Spec With HTML Docs
37+
38+
*** Keywords ***
39+
Validate XML Spec With HTML Docs
40+
Keyword Doc Should Be 0
41+
... <p>Example with <em>everything</em>!</p>
42+
... <p>This is the second paragraph. We also have an indented
43+
... example:</p>
44+
... <div class="code"><pre><span></span><code>keyword(1, 2, kwonly=3, extra=4)
45+
... </code></pre></div>
46+
...
47+
... <p>The end.</p>
48+
Argument Doc Should Be 0 0 own_line
49+
... <p>Documentation on same line.</p>
50+
Argument Doc Should Be 0 1 multiline
51+
... <p>Longer documentation that
52+
... spans multiple lines.</p>
53+
... <div class="code"><pre><span></span><code>Indentation is preserved.
54+
... </code></pre></div>
55+
Argument Doc Should Be 0 2 next_line
56+
... <p>Documentation on next line.</p>
57+
Argument Doc Should Be 0 3 empty_doc
58+
Return Doc Should Be 0
59+
... <p>Something useless.</p>
60+
... <p>On multiple lines
61+
... ${SPACE*8}with indentation.</p>
62+
Keyword Doc Should Be 1
63+
... <p><em>Creating keyword failed:</em> Documentation given to non-existing argument 'non_existing'.</p>
64+
Argument Doc Should Be 1 0 not_set
65+
Return Doc Should Be 1
66+
... <p>Zero</p>
67+
68+
Validate XML Spec With Raw Docs
69+
Keyword Doc Should Be 0
70+
... Example with *everything*!
71+
...
72+
... This is the second paragraph. We also have an indented
73+
... example:
74+
...
75+
... ${SPACE*4}keyword(1, 2, kwonly=3, extra=4)
76+
...
77+
... The end.
78+
Argument Doc Should Be 0 0 own_line
79+
... Documentation on same line.
80+
Argument Doc Should Be 0 1 multiline
81+
... Longer documentation that
82+
... spans multiple lines.
83+
...
84+
... ${SPACE*4}Indentation is preserved.
85+
Argument Doc Should Be 0 2 next_line
86+
... Documentation on next line.
87+
Argument Doc Should Be 0 3 empty_doc
88+
Return Doc Should Be 0
89+
... Something useless.
90+
...
91+
... On multiple lines
92+
... ${SPACE*8}with indentation.
93+
Keyword Doc Should Be 1
94+
... *Creating keyword failed:* Documentation given to non-existing argument 'non_existing'.
95+
Argument Doc Should Be 1 0 not_set
96+
Return Doc Should Be 1
97+
... Zero
98+
99+
Validate JSON Spec With HTML Docs
100+
Should Be Equal Multiline ${MODEL}[keywords][0][doc]
101+
... <p>Example with <em>everything</em>!</p>
102+
... <p>This is the second paragraph. We also have an indented
103+
... example:</p>
104+
... <div class="code"><pre><span></span><code>keyword(1, 2, kwonly=3, extra=4)
105+
... </code></pre></div>
106+
...
107+
... <p>The end.</p>
108+
Should Be Equal Multiline ${MODEL}[keywords][0][args][0][doc]
109+
... <p>Documentation on same line.</p>
110+
Should Be Equal Multiline ${MODEL}[keywords][0][args][1][doc]
111+
... <p>Longer documentation that
112+
... spans multiple lines.</p>
113+
... <div class="code"><pre><span></span><code>Indentation is preserved.
114+
... </code></pre></div>
115+
Should Be Equal Multiline ${MODEL}[keywords][0][args][2][doc]
116+
... <p>Documentation on next line.</p>
117+
Should Be Equal Multiline ${MODEL}[keywords][0][args][3][doc]
118+
Should Be Equal Multiline ${MODEL}[keywords][0][returnDoc]
119+
... <p>Something useless.</p>
120+
... <p>On multiple lines
121+
... ${SPACE*8}with indentation.</p>
122+
Should Be Equal Multiline ${MODEL}[keywords][1][doc]
123+
... <p><em>Creating keyword failed:</em> Documentation given to non-existing argument 'non_existing'.</p>
124+
Should Be Equal Multiline ${MODEL}[keywords][1][args][0][doc]
125+
Should Be Equal Multiline ${MODEL}[keywords][1][returnDoc]
126+
... <p>Zero</p>
127+
128+
Validate JSON Spec With Raw Docs
129+
Should Be Equal Multiline ${MODEL}[keywords][0][doc]
130+
... Example with *everything*!
131+
...
132+
... This is the second paragraph. We also have an indented
133+
... example:
134+
...
135+
... ${SPACE*4}keyword(1, 2, kwonly=3, extra=4)
136+
...
137+
... The end.
138+
Should Be Equal Multiline ${MODEL}[keywords][0][args][0][doc]
139+
... Documentation on same line.
140+
Should Be Equal Multiline ${MODEL}[keywords][0][args][1][doc]
141+
... Longer documentation that
142+
... spans multiple lines.
143+
...
144+
... ${SPACE*4}Indentation is preserved.
145+
Should Be Equal Multiline ${MODEL}[keywords][0][args][2][doc]
146+
... Documentation on next line.
147+
Should Be Equal Multiline ${MODEL}[keywords][0][args][3][doc]
148+
Should Be Equal Multiline ${MODEL}[keywords][0][returnDoc]
149+
... Something useless.
150+
...
151+
... On multiple lines
152+
... ${SPACE*8}with indentation.
153+
Should Be Equal Multiline ${MODEL}[keywords][1][doc]
154+
... *Creating keyword failed:* Documentation given to non-existing argument 'non_existing'.
155+
Should Be Equal Multiline ${MODEL}[keywords][1][args][0][doc]
156+
Should Be Equal Multiline ${MODEL}[keywords][1][returnDoc]
157+
... Zero

‎atest/robot/libdoc/libdoc_resource.robot‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,19 @@ Keyword Arguments Should Be
133133
[Arguments] ${index} @{expected}
134134
Verify Arguments Structure ${index} keywords/kw ${expected}
135135

136+
Argument Doc Should Be
137+
[Arguments] ${kw_index} ${arg_index} ${name} @{expected}
138+
VAR ${expected} @{expected} separator=\n
139+
${kws}= Get Elements ${LIBDOC} xpath=keywords/kw
140+
${args}= Get Elements ${kws}[${kw_index}] xpath=arguments/arg
141+
VAR ${arg} ${args}[${arg_index}]
142+
Element Text Should Be ${arg} ${name} xpath=name
143+
IF $expected
144+
Element Text Should Be ${arg} ${expected} xpath=doc
145+
ELSE
146+
Element Should Not Exist ${arg} xpath=doc
147+
END
148+
136149
Verify Arguments Structure
137150
[Arguments] ${index} ${xpath} ${expected}
138151
${kws}= Get Elements ${LIBDOC} xpath=${xpath}
@@ -161,6 +174,12 @@ Verify Arguments Structure
161174
Should Be Equal ${repr} ${exp_repr}
162175
END
163176

177+
Return Doc Should Be
178+
[Arguments] ${index} @{expected}
179+
VAR ${expected} @{expected} separator=\n
180+
${kws}= Get Elements ${LIBDOC} xpath=keywords/kw
181+
Element Text Should Be ${kws}[${index}] ${expected} xpath=returndoc
182+
164183
Return Type Should Be
165184
[Arguments] ${index} ${name} @{nested}
166185
${kws}= Get Elements ${LIBDOC} xpath=keywords/kw

‎atest/testdata/libdoc/DocStringParsing.py‎

Lines changed: 29 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,42 @@
1-
def keyword(arg, *, kwonly, **kwargs) -> str:
2-
"""Keyword with different argument and docstring.
1+
ROBOT_LIBRARY_DOC_FORMAT = "Markdown"
32

4-
This is second paragraph.
3+
4+
def arg_docs(own_line, multiline, *next_line, empty_doc, no_doc) -> str:
5+
"""Example with *everything*!
6+
7+
This is the second paragraph. We also have an indented
8+
example:
9+
10+
keyword(1, 2, kwonly=3, extra=4)
511
612
Args:
7-
arg: Documentation at same line
8-
kwonly: With a long description that
9-
spans multiple lines
13+
own_line: Documentation on same line.
14+
multiline (ignored): Longer documentation that
15+
spans multiple lines.
1016
11-
def keyword(arg, *, kwonly, **kwargs) -> str:
12-
pass
13-
kwargs:
14-
Documentation at next line
17+
Indentation is preserved.
1518
16-
Here is more text in the docstring after the argument.
19+
next_line:
20+
Documentation on next line.
21+
empty_doc:
1722
1823
Returns:
19-
This documentation for the return value
24+
Something useless.
2025
21-
This ends the docstring.
22-
"""
26+
On multiple lines
27+
with indentation.
2328
24-
return "This is a return value."
29+
The end.
30+
"""
31+
return ""
2532

2633

27-
def keyword_doc_not_existing_args(no_doc, other):
28-
"""Doc
34+
def doc_for_not_existing_arg(not_set) -> int:
35+
"""
36+
Arguments:
37+
not_set: Not set due to an error.
38+
non_existing: This causes that error.
2939
30-
Args:
31-
no_doc:
32-
other: Documentation for argument that does exist
33-
does_not_exist: Documentation for argument that does not exist
40+
RETURNS: Zero
3441
"""
35-
return "This is a return value."
42+
return 0

0 commit comments

Comments
 (0)