-
Notifications
You must be signed in to change notification settings - Fork 18
Pull Request for Comments to the Syllabus #45
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
asimell
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Doing all chapters at once for a single review will take some time, so I'll drop comments by chapter.
Comments for chapter 2.
|
|
||
| After executing a suite, Robot Framework, by default, generates tree output files in the output directory. These artifacts provide detailed execution results: | ||
|
|
||
| - **`output.xml`**: A machine-readable file containing **ALL** logged execution details, limited by the given log-level. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is output.json part of this syllabus? It's a new feature, so is it just forgotten or intentionally left out?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@asimell no. its not yet. also xunit.xml and legacy output is not.
only the standard.
* Restructuring sentence in 1.4 This sentence was not very clear to me originally. Fixed a typo (users -> users' ) and restructured the sentence so it made more sense to me. * formatting
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Gerwin <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
Co-authored-by: Aleksi Simell <[email protected]>
|
|
||
| **Key characteristics of Keyword Teardown:** | ||
| - Keyword Teardown is a single keyword call with potential argument values. | ||
| - Executed after the keyword body has been executed, regardless of its status. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- If the Keyword Teardown fails, the test|task is marked as failed in reports and logs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
no. see setup
| See [2.5.2.6 Named-Only Arguments](chapter-02/05_keyword_interface.md#2526-named-only-arguments) for more information about this kind of argument. | ||
|
|
||
|
|
||
| ## 2.5.2 Keyword Arguments |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Each subsection for different argument types would benefit from one or more examples. Probably example of libdoc keyword documentation would be enough. Currently, this is probably one of the most abstract sections of the syllabus. In theory. In practice one does not really need to think about these (outside designing and implementing keywords, of course).
I must acknowledge that the chapter starts with examples, but those are far away from the detailed per argument type sections.
|
|
||
|
|
||
|
|
||
| ## 0.2 About "Robot Framework® Certified Professional" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should the syllabus also explain the exam a bit? As in how many questions it will have, what types of questions, weight on different question domains, etc.?
asimell
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Comments for chapter 3.
| &{participant_1} name=Alice age=23 | ||
| &{participant_2} name=Bob age=42 | ||
| &{participant_3} name=Charlie age=33 | ||
| &{participant_4} name=Pekka age=44 | ||
| @{participants} ${participant_1} ${participant_2} ${participant_3} ${participant_4} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should these follow the general best practices that all suite variables are in upper case?
| | **Keyword Section** | This section allows you to define locally scoped user keywords that can only be used within the same suite where they are defined. | | ||
| | **Robot Framework Sections** | Different parts of a Robot Framework suite file that organize the content. | | ||
| | **Settings Section** | This section is used to configure various aspects of the test/task suite. | | ||
| | **Variables Section** | This section is used to define suite variables that are used in the suite or its tests/tasks or inside their keywords. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Glossary should probably be sorted alphabetically (seems was so in the beginning but then got mixed).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
second that- common practice for appendices
| | [`LO-5.2.1`](chapter-05/02_control_structures.md#521-if-statements) | K2 | Understand the purpose and basic concept of IF-Statements | | ||
| | [`LO-5.2.4`](chapter-05/02_control_structures.md#524-for-loops) | K2 | Understand the purpose and basic concept of FOR Loops | | ||
| | [`LO-5.2.5`](chapter-05/02_control_structures.md#525-while-loops) | K2 | Understand the purpose and basic concept of WHILE Loops | | ||
| | [`LO-5.2.6`](chapter-05/02_control_structures.md#526-break-and-continue) | K2 | Understand the purpose and basic concept of the BREAK and CONTINUE statements | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Before K2 (Understand) objective for conditionals and iterators, it's probably worth adding K1 - recalling objective (first know what it is, then understand each one).
For example,
Recall at least three control structures available in Robot Framework,
or something similar.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Punctuation seems inconsistent - some sentences in the table end with period ., some - without.
| - **Indentation based blocks**: Code blocks like test, task or keyword bodies are defined by indentation. | ||
| This makes the structure clear and easy to follow. | ||
| - **Reduced use of special characters**: Compared to programming languages the focus is on reducing special characters, making the syntax human-readable and user-friendly. | ||
| - **String first**: Unquoted strings are considered as strings, while variables need special syntax. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This was not super clear to me what does it mean "while variables need special syntax".
Tried to explain it like so:
Variables in Robot Framework must use ${variable} syntax, while plain text like Hello World is automatically treated as a string without needing quotes.
The ${variable} syntax tells Robot Framework "this is a variable, use its value" rather than treating it as a literal string.
website/docs/chapter-01/03_syntax.md
Outdated
| While tests and tasks are organized into suites, **keywords** are organized into **Resource Files** and **Keyword Libraries**. | ||
|
|
||
| - **Resource Files**: Contain **User Keywords**, and are also used to organize the importing of libraries and defining variables. These are considered to be part of the test|task data in the *Definition Layer*. | ||
| - **Keyword Libraries**: Contain **Library Keywords**, which are typically implemented in Python or other technologies and except of the standard libraries are not part of Robot Framework itself and can be either custom-made or third-party libraries implemented by the Robot Framework community. These are considered to be part of the *Adaptation Layer*. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This sounds painful to my English ear:
"and except of the"
Should be:
"and apart from the standard libraries are not part of Robot Framework itself"
But that also sound horrible because it contains "apart" and "part".
Maybe something like:
"Keyword Libraries are collections of Library Keywords that are implemented in Python or other programming languages. While standard libraries come bundled with Robot Framework, most Keyword Libraries are external components that must be installed separately."
website/docs/chapter-04/05_skip.md
Outdated
| The difference between `--skip` and `--exclude` is that `--skip` will mark the tests|tasks as skipped in the report and log, while `--exclude` will not execute them at all. | ||
| Therefore skip is better for documenting that a specific test|task was not executed for a specific reason. | ||
|
|
||
| **Example**: If there is a defect in the System under Test (SUT) and a test|task has been written to reproduce the defect and tests its resolution, but the defect is not yet resolved, the test|task can be tagged with the defect-number and skipped until the defect should be resolved. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this sounds better as:
"until the defect is resolved."
OR
"until the defect has been resolved."
| Several factors influence variable priority in Robot Framework: the type of variable, the time of (re-)definition, and the variable’s scope. | ||
|
|
||
| In general, there are two types of variables regarding how they are created: | ||
| - Statically defined or imported variables (e.g., in the `*** Variables ***` section, command-line options, imported resource files) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a bit weird because it talks about two types of variable then mentions three
- Statically defined
- Imported
- Dynamically created
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
there are two bullet points.
Statically defined and imported variables are one type.
Dynamically assigned during execution is the other one
| | **Keyword-Driven** | A testing approach where test cases are defined using keywords that represent actions or operations. | | ||
| | **Library** | A collection of keywords and functions that can be used in test automation. | | ||
| | **Libdoc** | A tool used to generate keyword documentation for libraries and resource files. | | ||
| | **Rebot** | The main executable used to execute suites and post-process execution results to generate reports. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Glossary has Libdoc and Rebot but not Robot
i.e.
https://robotframework.org/robotframework-RFCP-syllabus/docs/chapter-02/executing
Somehow I think in the glossary Rebot is mixing Robot and Rebot.
| | **Root Suite** | The top-level suite that contains all other suites and test cases. | | ||
| | **Suite Directory** | A directory that contains multiple suite files, which can include test cases and tasks organized hierarchically. | | ||
| | **Suite File** | A \*.robot file that contains at least one test case or task. | | ||
| | **Task** | A unit of work that can be executed, similar to a test case but typically focused on automation tasks. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should "automation tasks" be "robotic process automation (RPA)"?
kstine
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overall fairly complete, there are only a few spots that explanations or layout could be improved.
| @@ -0,0 +1,77 @@ | |||
|
|
|||
| # 1.5 Organization and Licensing | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reorder:
1.5 Licensing and Foundation and Web pages
to match order
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe
However ordering means renumbering of LOs which is a massive change!
| Legend: | ||
| ```plaintext | ||
| ▷ Directory (No Suite) | ||
| ▶︎ Suite Directory | ||
| ◻︎ File (No Suite) | ||
| ◼︎ Suite File | ||
| ``` | ||
|
|
||
| Example: | ||
| ```plaintext | ||
| ----- Tree Structure / Order --------- | ---- Suite Name --------- | ||
| ▶︎ Root_Suite | Root Suite | ||
| ◼︎ A_Suite.robot | A Suite | ||
| ▶︎ Earlier_Suite_Directory | Earlier Suite Directory | ||
| ◼︎ B_Suite.robot | B Suite | ||
| ◼︎ C_Suite.robot | C Suite | ||
| ▷ Keywords (No Suite) | | ||
| ◻︎ technical_keywords.resource | | ||
| ▶︎ Later_Suite_Directory | Later Suite Directory | ||
| ◼︎ 01__FirstSuite.robot | First Suite | ||
| ◼︎ 02__SecondSuite.robot | Second Suite | ||
| ▶︎ 03__ThirdSuite | Third Suite | ||
| ◼︎ 01__FirstSubSuite.robot | First Sub Suite | ||
| ◼︎ 02__SecondSubSuite.robot | Second Sub Suite | ||
| ◼︎ 04__FourthSuite.robot | Fourth Suite |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should use a standard tree diagram here as found in markdown.
example: https://www.w3schools.io/file/markdown-folder-tree/
This is difficult to read.
| - `Test Setup`/`Task Setup` (locally: `[Setup]`) and `Test Teardown`/`Task Teardown` (locally `[Teardown]`) define which keywords are executed before and after each individual test|task. The local setting overrides the suite's default. See [4.1 Setups (Suite, Test|Task, Keyword)](chapter-04/01_setups.md) and | ||
| [4.2 Teardowns (Suite, Test|Task, Keyword)](chapter-04/02_teardowns.md) for more information. | ||
|
|
||
| - `Test Timeout`/`Task Timeout` (locally `[Timeout]`) defines the maximum time a test|task is allowed to run before it is marked as failed. The local setting overrides the suite's default. | ||
|
|
||
| - `Test Tags`/`Task Tags` (locally `[Tags]`) define tags that are assigned to tests|tasks in the suite and can be used to filter tests|tasks for execution or for attributing information to the tests|tasks. The local setting appends or removes tags defined by the suite's default. See [4.4 Test|Task Tags and Filtering Execution](chapter-04/04_tags.md) for more information. | ||
|
|
||
| - `Test Template`/`Task Template` (locally `[Template]`) defines a template keyword that defines the test|task body and is typically used for Data-Driven Testing where each test has the same keywords but different argument data. The local setting overrides the suite's default. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
#I would have said something else beside locally:
This may seem verbose but it is easier to understand:
Corresponds to the [<setting>] setting.
ALL of the settings should be described as:
- <setting> Description
With each setting with its own line. i.e. break up the Test Setup / Task Setup from Test Teardown / Task Teardown
The user guide lays out these settings very well: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#setting-section-1
A clear list of settings and definitions- very concise and consistent.
|
|
||
| This section can also define keywords called for execution flow control, such as `Suite Setup` and `Suite Teardown`, which are executed before and after the suite's tests run. See [4.1 Setups (Suite, Test|Task, Keyword)](chapter-04/01_setups.md) and | ||
| [4.2 Teardowns (Suite, Test|Task, Keyword)](chapter-04/02_teardowns.md) for more information. | ||
|
|
||
| Additionally, some settings can define defaults for all tests|tasks in the suite, which can be extended or overwritten in the individual tests|tasks. | ||
| Those settings are prefixed with either `Test` or `Task`, according to the type of suite and the following section type (`*** Test Cases ***` or `*** Tasks ***`), like `Test Timeout`, while the local setting is in square brackets and without the prefix like: `[Timeout]`. | ||
|
|
||
|
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I placed all my main comments in the next comment.
It is good to have a paragraph of explanation of the settings section, but the settings should be clearly presented outside of a paragraph structure.
| @@ -0,0 +1,453 @@ | |||
|
|
|||
| # 5.1 Advanced Variables | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There is a concept of Advanced Variable features in the user guide: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#advanced-variable-features
Not sure if the syllabus lines up with the user guide.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
no. but for the syllabus this here is advanced stuff.
| | **Keyword Section** | This section allows you to define locally scoped user keywords that can only be used within the same suite where they are defined. | | ||
| | **Robot Framework Sections** | Different parts of a Robot Framework suite file that organize the content. | | ||
| | **Settings Section** | This section is used to configure various aspects of the test/task suite. | | ||
| | **Variables Section** | This section is used to define suite variables that are used in the suite or its tests/tasks or inside their keywords. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
second that- common practice for appendices
| ```robotframework | ||
| *** Test Cases *** | ||
| Quick Check | ||
| IF ${user} == 'Admin' Log Admin access granted. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| IF ${user} == 'Admin' Log Admin access granted. | |
| IF '${user}' == 'Admin' Log Admin access granted. |
|
|
||
| This status is used if an element was executed but encountered an error or exception that was not expected. | ||
|
|
||
| A failure typically causes the subsequent keywords to be skipped. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would avoid the use of 'skipped' here, it is ambiguous. Instead mention specifically 'NOT RUN' as that is what keywords get assigned as a status when a previous keyword is given a "FAIL" status.
| It is possible to define the order without influencing the name of the suite by adding a prefix followed by two underscores `__` to the name of the directory or file. This prefix is NOT considered part of the name. | ||
| So `01__First_Suite.robot` sets the suite name to `First Suite`, while `2_Second_Suite.robot` sets the suite name to `2 Second Suite`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| It is possible to define the order without influencing the name of the suite by adding a prefix followed by two underscores `__` to the name of the directory or file. This prefix is NOT considered part of the name. | |
| So `01__First_Suite.robot` sets the suite name to `First Suite`, while `2_Second_Suite.robot` sets the suite name to `2 Second Suite`. | |
| It is possible to define the order without influencing the name of the suite by adding an arbitrary prefix followed by two underscores `__` to the name of the directory or file. This prefix is NOT considered part of the name. | |
| So both `01__First_Suite.robot` or `345foo__FirstSuite.robot` set the suite name to `First Suite`, while `2_Second_Suite.robot` results in a regular suite name `2 Second Suite`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Won't the 345foo__FirstSuite.robot suite file set the name FirstSuite in your correction?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Won't the
345foo__FirstSuite.robotsuite file set the nameFirstSuitein your correction?
Yes, you're right! :-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It may be possible to use this characters in the prefix, but we are not obligated to mention every weird thing that is possible.
So i do not see the benefit of overloading people sith this level of detail/possibilities.
I think the numbering is the most used and obvious option.
| The body ends when either a new un-indented test case name is defined | ||
| or another section like `*** Keywords ***` starts | ||
| or the end of the file is reached. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| The body ends when either a new un-indented test case name is defined | |
| or another section like `*** Keywords ***` starts | |
| or the end of the file is reached. | |
| The body ends when either a new un-indented name of the section type is defined (keyword or testcase/task) | |
| or another section like `*** Keywords ***` starts | |
| or the end of the file is reached. |
| *** Settings *** | ||
| Documentation This is the first line of suite documentation. | ||
| ... | ||
| ... This is the second line of suite documentation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ... This is the second line of suite documentation. | |
| ... This is the first line in the second paragraph of suite documentation. |
| Test Case Name | ||
| [Documentation] This is the first line of test documentation. | ||
| ... | ||
| ... This is the second line of test documentation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ... This is the second line of test documentation. | |
| ... This is the first line in the second paragraph of test documentation. |
| | `${EXECDIR}` | An absolute path to the directory where test execution was started from. | | ||
| | `${OUTPUT_DIR}` | An absolute path to the directory where output files, like `output.xml`, `log.html`, and `report.html`, are written. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would suggest to use a consistent style for all the variable names:
${EXECDIR}${EXEC DIR}${EXEC_DIR}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
tell that pekka and not me ;-)
Call Get Variables and be surprised. ;-)
|
|
||
| If the path to a single file is given as **Root Suite** directly to Robot Framework, only this file is parsed. | ||
|
|
||
| If a directory path is given, starting at this location, Robot Framework will parse all `*.robot` files and directories within this path. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In this section, I wonder if we want to mention the third 'Root Suite' that is possible. Someone that was being taught mentioned that Robot allows for 'multiple files / folders' to be added as per:https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#specifying-test-data-to-be-executed
When this is done. Robot creates a 'virtual' suite from which to generate the overview of suite files and folders. A quote from user guide:
The name of the created test suite is got from child suite names by concatenating them together with an ampersand (&) and spaces.
It might be a bit too complicated for 'RFCP level, but perhaps a mention of this thing might be necessary.
Updated PR preview workflow to include review gating and additional event types.
Updated the PR preview workflow to enhance comments and domain handling.
This PR is there to make comments to the syllabus directly.