Pull Request for Comments to the Syllabus #45
Conversation
|
|
||
| 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.
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.
@asimell no. its not yet. also xunit.xml and legacy output is not.
only the standard.
| but doing that should not give the impression that a descriptive documentation is not needed. | ||
|
|
||
| Documentation is sometimes lean and sometimes extensive, depending on the complexity of the keyword. | ||
| The documentation should describe what the keyword does, how it should be used, and what the expected arguments are. |
There was a problem hiding this comment.
Also, it should describe if the keyword returns any values.
* 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 Setup:** | ||
| - Keyword Setup is a single keyword call with potential argument values. | ||
| - Executed before the keyword's body. | ||
| - If the Keyword Setup fails, the keyword's body is not executed. |
There was a problem hiding this comment.
- If the Keyword Setup fails, the test|task is marked as failed, and the keyword's body is not executed.
There was a problem hiding this comment.
not necessarily.
the keyword would be fail, but not the test|task.
let's assume, the failing keyword is in a try block.
|
|
||
| **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.
- If the Keyword Teardown fails, the test|task is marked as failed in reports and logs.
| 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.
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.
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.?
| - **Naming Case**: Which case shall be used? (i.e. `Title Case`, `camelCase`, `snake_case`, `kebab-case`, or `sentence case`, etc. ) (from a readability perspective, `Title Case` or `Sentence case` are recommended) | ||
| - **Grammatical Form/Mood**: Which form shall be used for actions and verifications/assertions? (i.e. `Imperative` for both like `Click Button`, `Verify Text`. Or i.e. `Declarative`/`Indicative` for assertions like `Text Should Be`, `Element Should Be Visible`) | ||
| - **Word/Character Count**: How man words or characters shall be used in a keyword name? (i.e. less than 7 words) | ||
| - **Argument Count**: How many arguments shall a keyword have? (i.e. less than 5) | ||
| - **Documentation**: How shall the documentation be structured and which information shall be included or is it required at all? |
There was a problem hiding this comment.
i.e. != e.g.
| - **Naming Case**: Which case shall be used? (i.e. `Title Case`, `camelCase`, `snake_case`, `kebab-case`, or `sentence case`, etc. ) (from a readability perspective, `Title Case` or `Sentence case` are recommended) | |
| - **Grammatical Form/Mood**: Which form shall be used for actions and verifications/assertions? (i.e. `Imperative` for both like `Click Button`, `Verify Text`. Or i.e. `Declarative`/`Indicative` for assertions like `Text Should Be`, `Element Should Be Visible`) | |
| - **Word/Character Count**: How man words or characters shall be used in a keyword name? (i.e. less than 7 words) | |
| - **Argument Count**: How many arguments shall a keyword have? (i.e. less than 5) | |
| - **Documentation**: How shall the documentation be structured and which information shall be included or is it required at all? | |
| - **Naming Case**: Which case shall be used? (e.g. `Title Case`, `camelCase`, `snake_case`, `kebab-case`, or `sentence case`, etc. ) (from a readability perspective, `Title Case` or `Sentence case` are recommended) | |
| - **Grammatical Form/Mood**: Which form shall be used for actions and verifications/assertions? (e.g. `Imperative` for both like `Click Button`, `Verify Text`. Or e.g. `Declarative`/`Indicative` for assertions like `Text Should Be`, `Element Should Be Visible`) | |
| - **Word/Character Count**: How many words or characters shall be used in a keyword name? (e.g. less than 7 words) | |
| - **Argument Count**: How many arguments shall a keyword have? (e.g. less than 5) | |
| - **Documentation**: How shall the documentation be structured and which information shall be included or is it required at all? |
There was a problem hiding this comment.
Cool. I knew there was a misspelled word in there somewhere. (line 426)
| It is strongly recommended to have all these possible arguments to the library itself defined with default values; | ||
| however, that is not always possible. |
There was a problem hiding this comment.
This phrasing makes this feel out of scope for this syllabus. The reader is expected to know how to import libraries correctly, not how to create a library with import parameters. Therefore, the reader shouldn't need to be aware of what are the strong recommendations for library development (i.e. to add default values to possible arguments), but to know how to identify if a library requires mandatory arguments and how to import a library with arguments.
| | `${CURDIR}` | An absolute path to the directory where the current suite or resource file is located. This variable is case-sensitive. | | ||
| | `${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. | | ||
| | `${TEMPDIR}` | An absolute path to the system temporary directory. In UNIX-like systems, this is typically /tmp, and in Windows, it is c:\Documents and Settings\<user>\Local Settings\Temp. | |
There was a problem hiding this comment.
\< doesn't render correctly. The backslash needs to be escaped.
| | `${TEMPDIR}` | An absolute path to the system temporary directory. In UNIX-like systems, this is typically /tmp, and in Windows, it is c:\Documents and Settings\<user>\Local Settings\Temp. | | |
| | `${TEMPDIR}` | An absolute path to the system temporary directory. In UNIX-like systems, this is typically /tmp, and in Windows, it is c:\Documents and Settings\\<user>\Local Settings\Temp. | |
| &{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.
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.
Glossary should probably be sorted alphabetically (seems was so in the beginning but then got mixed).
There was a problem hiding this comment.
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.
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.
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.
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.
| 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.
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."
| Click On Coordinates x=82 y=70 | ||
| ``` | ||
|
|
||
| Calling keywords that has a "Variable Number of Positional Arguments" does require to set all preceding arguments by their position if the "Variable Number of Positional Arguments" shall be set. |
There was a problem hiding this comment.
"Calling keywords that has a"
->
"Calling keywords that have a"
|
|
||
| See [2.1.2 Sections and Their Artifacts](chapter-02/01_suitefile.md#212-sections-and-their-artifacts) for an introduction to sections in suites. | ||
|
|
||
| Other than in suites, resource files do not allow the `*** Test Cases ***` or `*** Tasks ***` sections. |
There was a problem hiding this comment.
This is a bit confusing it implies that resource files can be in suite files. Which I understand is not correct.
I read it as "if a resource file is in a suite then it can have a *** Test Cases *** or *** Tasks *** section"
I think resource files can never have this section.
There was a problem hiding this comment.
Agreed on the confusion. Had a similar reaction when reading it today. I would suggest a sentence such as this:
| Other than in suites, resource files do not allow the `*** Test Cases ***` or `*** Tasks ***` sections. | |
| In difference to 'suite'-files, resource files do **not** allow the `*** Test Cases ***` or `*** Tasks ***` sections. |
|
|
||
| The advantage of this approach is that each test|task is executed separately with its own name and data set. | ||
| Each test|task appears in the statistics and reports. | ||
| Single tests|tasks can be filtered and re-executed or tagged. |
There was a problem hiding this comment.
Would be nice to see an example of this. I have not seen a Test case that uses a Suite level Test Template tagged locally with [Tags]. I'm scratching my head here thinking how to do it :-)
| ``` | ||
| - Executes the `Log` keyword if `${status}` is the string `SUCCESS`. | ||
|
|
||
| ## 5.2.2 IF/ELSE IF/ELSE Structure |
There was a problem hiding this comment.
Mentioning IF/ELSE twice might be confusing, especially, in the section title. I think, IF/ELSE Structure would be more clear. Following examples already show that they can be used consecutively.
| Specification styles define how the automation process or test cases are structured, focusing on how actions and verifications are expressed. | ||
| These styles can be applied to all types of automation, including both testing and robotic process automation (RPA). |
There was a problem hiding this comment.
These sentences feel a bit complicated. How about:
| Specification styles define how the automation process or test cases are structured, focusing on how actions and verifications are expressed. | |
| These styles can be applied to all types of automation, including both testing and robotic process automation (RPA). | |
| Specification styles define how test cases or tasks are structured, and how actions and verifications are described. |
| :::: | ||
|
|
||
| Specification styles define how the automation process or test cases are structured, focusing on how actions and verifications are expressed. | ||
| These styles can be applied to all types of automation, including both testing and robotic process automation (RPA). |
There was a problem hiding this comment.
Before describing their applications (in the following) paragraphs, would be good to first mention which styles exist:
| These styles can be applied to all types of automation, including both testing and robotic process automation (RPA). | |
| There are three specification styles in Robot Framework: **Keyword-Driven**, **Behavior-Driven** and **Data-Driven**. |
|
|
||
| Both styles can be mixed, even within the same test or task, but it is strongly recommended to have separate styles for separate purposes and not mix them within the same body. | ||
| One practical solution would be to define acceptance test cases that cover users' expectations in a declarative *Behavior-Driven Style*, while using keywords that are implemented in an imperative *Keyword-Driven style*. | ||
| Further system level test cases, that are not covering acceptance criteria could be written in a *Keyword-Driven style*. |
There was a problem hiding this comment.
Lines 19-20 feels more like a practical advice how things could be done. Maybe not relevant to the Syllabus. I think, this paragraph could be omitted.
There was a problem hiding this comment.
Overall, the intro sub-section can be restructured a bit, so that first is general definition of what "Specification Style" means, then what styles exist in RF, and then short, generic description of each one.
Also, language and grammar could be polished a bit.
| All those characters or character sequences that are interpreted as control characters can be escaped by a backslash `\`. | ||
| This means that the character following the backslash is interpreted as a normal character and not as a control character. | ||
|
|
||
| This leads to the fact that a backslash itself must be escaped by another backslash to be interpreted as a normal backslash character. Therefore it is strongly recommended to use forward slashes `/` as path separators in paths also on windows environments and avoid backslashes `\` when ever possible. |
There was a problem hiding this comment.
| This leads to the fact that a backslash itself must be escaped by another backslash to be interpreted as a normal backslash character. Therefore it is strongly recommended to use forward slashes `/` as path separators in paths also on windows environments and avoid backslashes `\` when ever possible. | |
| This leads to the fact that a backslash itself must be escaped by another backslash to be interpreted as a normal backslash character. Therefore it is strongly recommended to use forward slashes `/` as path separators in paths also on windows environments and avoid backslashes `\` whenever possible. |
| - `Login User With Password` | ||
| - `Denied Login With Wrong Password` | ||
|
|
||
| Both test the login functionality of a system by calling four keywords in their bodies. |
There was a problem hiding this comment.
Examples could be moved after this line, then, following explanations would be clearer.
| robot <path_to_root_suite> | ||
| ``` | ||
|
|
||
| In case of the above given example where a single suite file named `TestSuite.robot` is stored in a directory `robot_files`, to execute the example test suite the following command is used, if the current working directory of the terminal is the directory containing the `robot_files` directory: |
There was a problem hiding this comment.
It seems the example this sentence is referring to is missing?
| ``` | ||
|
|
||
| This command starts the Robot Framework execution by first parsing all files in the given directory tree that have the extension `.robot`, | ||
| then creating an execution model and then executing all suites and test cases in that model. |
There was a problem hiding this comment.
| then creating an execution model and then executing all suites and test cases in that model. | |
| then creates an execution model and finally, executes all suites in that model. |
Since Suites are practically a collection of test cases or tasks, I think "executing all suites and test cases" is repetitive.
|
|
||
| :::K2[LO-2.3.2] | ||
|
|
||
| Explain the execution artifacts generated by Robot Framework. |
There was a problem hiding this comment.
This LO should probably be preceded with K1: Recall the three standard output files produced by robot run.
|
|
||
| :::: | ||
|
|
||
| A **Test|Task Setup** is executed before a single test|task runs. |
There was a problem hiding this comment.
Maybe clarify here that it is executed before "every" Test|Task in the suite.
|
|
||
| :::: | ||
|
|
||
| A **Keyword Setup** is executed before the body of a user keyword is executed. |
There was a problem hiding this comment.
Maybe clarify here:
Unlike with tests, it is not possible to specify a common setup or teardown for all keywords in a certain file.
|
|
||
| :::: | ||
|
|
||
| A **Keyword Teardown** is executed after a user keyword body has been executed. |
There was a problem hiding this comment.
Maybe clarify here (same for teardown):
Unlike with tests, it is not possible to specify a common setup or teardown for all keywords in a certain file.
|
|
||
| # 4.3 Initialization Files | ||
|
|
||
| ::::lo[Learning Objectives] |
There was a problem hiding this comment.
LO here read:
LO-4.3 Recall how to define an Initialization Files and its purpose
Either you need to say:
"Recall how to define an Initialization File and its purpose"
OR
"Recall how to define Initialization Files and their purpose"
|
|
||
| - **Temporal Exclusion of Tests|Tasks**: To prevent failing tests|tasks for known issues to run until the issue is resolved. | ||
| - **Conditional Execution**: Skip tests|tasks dynamically based on runtime conditions, i.e. if Suite Setup detected an issue. | ||
| - **Unsupported Scenarios**: Mark tests|tasks as skipped in environments where they cannot run, but shall be in logs. |
There was a problem hiding this comment.
I think this sounds better as:
"but should be in logs"
OR
"but should be logged"
| 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.
I think this sounds better as:
"until the defect is resolved."
OR
"until the defect has been resolved."
|
|
||
| **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. | ||
|
|
||
| **Example**: Assuming there are different test environments and some tests can only be executed on specific environments, the tests can be tagged with the environment name and skipped on all other environments. |
There was a problem hiding this comment.
"executed on specific environments"
->
"executed in specific environments"
"skipped on all other environments"
->
"skipped in all other environments"
| - Statically defined or imported variables (e.g., in the `*** Variables ***` section, command-line options, imported resource files) | ||
| - Dynamically created variables during Robot Framework execution (e.g., using the `VAR` syntax, assignment of return values from keywords or keyword arguments) | ||
|
|
||
| Built-in variables cannot generally be sorted into one of these categories, as some are predefined globally while others are created during execution with a `SUITE` or `TEST` scope. |
There was a problem hiding this comment.
It would be nice to see an example how some Built-in variables can be Statically defined or imported variables and some can be Dynamically created. It's hard to grasp this concept.
| 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.
This is a bit weird because it talks about two types of variable then mentions three
- Statically defined
- Imported
- Dynamically created
| &{participant_one} name=Alice age=23 | ||
| &{participant_two} name=Bob age=42 | ||
|
|
||
| *** Keywords *** |
There was a problem hiding this comment.
In this example the *** Keywords *** section comes before the *** Test Cases *** section
In section 2.1.2 Sections and Their Artifacts it states that:
The following sections are recognized by Robot Framework and are recommended to be used in the order they are listed:
*** Settings ***
*** Variables ***
*** Test Cases *** or *** Tasks *** (mandatory in Suite Files)
*** Keywords ***
*** Comments ***
I know this because I got told off for doing it in my Accredited Trainer training material review :-)
There was a problem hiding this comment.
According to the Style Guide *** Comments *** are first.
https://docs.robotframework.org/docs/style_guide#sections
| END | ||
| ``` | ||
|
|
||
| `WHILE` loops have a configurable iteration limit in Robot Framework. |
There was a problem hiding this comment.
Would be nice to have an example of the "configurable iteration limit" here it tells you it exists but not how to use it and leaves you wondering.
| ```robotframework | ||
| *** Test Cases *** | ||
| Scroll Down Until Element Visible | ||
| WHILE True # This would loop to the max iteration limit |
There was a problem hiding this comment.
"WHILE True" is bad practice in my opinion, I think you would try to avoid this at all costs. Even though this is just an example maybe a less precarious example would be better.
There was a problem hiding this comment.
WHILE True is a little more okay if it includes the limit feature of WHILE. As per your earlier comment.
| | **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.
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.
Should "automation tasks" be "robotic process automation (RPA)"?
| @@ -0,0 +1,77 @@ | |||
|
|
|||
| # 1.5 Organization and Licensing | |||
There was a problem hiding this comment.
Reorder:
1.5 Licensing and Foundation and Web pages
to match order
| 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.
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.
#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.
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.
|
|
||
| *** Test Cases *** | ||
| Returning a List Example | ||
| ${files} List Files In Directory server/logs |
There was a problem hiding this comment.
Inconsistent styling for = sign.
Will examples adopt the optional syntax or is mixing styles purposeful?
| @@ -0,0 +1,453 @@ | |||
|
|
|||
| # 5.1 Advanced Variables | |||
There was a problem hiding this comment.
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.
| &{participant_one} name=Alice age=23 | ||
| &{participant_two} name=Bob age=42 | ||
|
|
||
| *** Keywords *** |
There was a problem hiding this comment.
According to the Style Guide *** Comments *** are first.
https://docs.robotframework.org/docs/style_guide#sections
|
|
||
| Robot Framework has a set of built-in variables that can be used in test cases, keywords, and other places. Some examples are: | ||
|
|
||
| | Variable | Description | |
There was a problem hiding this comment.
I think we are missing some other built-in variables: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#built-in-variables
i.e. ${/}, ${:}, and ${\n}
| ```robotframework | ||
| *** Test Cases *** | ||
| Scroll Down Until Element Visible | ||
| WHILE True # This would loop to the max iteration limit |
There was a problem hiding this comment.
WHILE True is a little more okay if it includes the limit feature of WHILE. As per your earlier comment.
| | **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.
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.
| IF ${user} == 'Admin' Log Admin access granted. | |
| IF '${user}' == 'Admin' Log Admin access granted. |
|
|
||
| If a variable is defined in the `*** Variables ***` section of a suite file and is dynamically defined using the `VAR` syntax at the suite level, the variable value is overwritten with the new value. | ||
|
|
||
| If a global variable is defined using the command line, and a suite-level variable with the same name is dynamically defined, the suite variable now shadows the global variable and has higher priority as long as the suite is in scope. Once the suite is finished or a sub-suite is executed, the global variable returns to scope with higher priority. |
There was a problem hiding this comment.
I'm not sure if 'shadows' is the correct term in this context. For clarity sake, I think perhaps 'masked' might be better. But other terms can be considered too if you can come up with something. I've decided to mention it here because it's got a proper example.
Shadow is usually perceived as something that is 'behind' something. Whereas in this case the dynamically defined suite variable is at the forefront. I would argue that the global variable is the shadow in this example, as it returns when the suite scope is gone again.
There was a problem hiding this comment.
For further context, I was mostly confused because when mounting NFS systems 'over' folders systems, the covered filestructures are called shadow file system.
| - **Scalar Variables**: Store values as a single entity and are represented by the dollar-syntax `${variable_name}`. | ||
| - **List Variables**: Store multiple values in a list structure. They are created using the at-syntax `@{list_variable_name}`. | ||
| - **Dictionary Variables**: Store key-value pairs in a dictionary structure. They are created using the ampersand-syntax `&{dictionary_variable_name}`. | ||
| - **Environment Variables** (read-only): Read access to environments variables of the operating system unsing the percent-syntax `%{ENV_VAR_NAME}`. |
There was a problem hiding this comment.
Typo :
| - **Environment Variables** (read-only): Read access to environments variables of the operating system unsing the percent-syntax `%{ENV_VAR_NAME}`. | |
| - **Environment Variables** (read-only): Read access to environment variables of the operating system using the percent-syntax `%{ENV_VAR_NAME}`. |
| # 5.2 Control Structures | ||
|
|
||
| Robot Framework is a Turing-complete language and supports all common control structures, including IF-Statements, FOR-Loops, WHILE-Loops and more. | ||
| While it is not expected that RCFPs can write complex control structures, they should understand their purpose. |
There was a problem hiding this comment.
| While it is not expected that RCFPs can write complex control structures, they should understand their purpose. | |
| While it is not expected that RFCPs can write complex control structures, they should understand their purpose. |
|
|
||
| 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.
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.
| 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.
Won't the 345foo__FirstSuite.robot suite file set the name FirstSuite in your correction?
There was a problem hiding this comment.
Won't the
345foo__FirstSuite.robotsuite file set the nameFirstSuitein your correction?
Yes, you're right! :-)
| 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.
| 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.
| ... 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.
| ... This is the second line of test documentation. | |
| ... This is the first line in the second paragraph of test documentation. |
| Well-named keywords make tests more readable and easier to understand. | ||
| Robot Framework supports Unicode and allows the use of special characters and even Emojis in keyword names. | ||
|
|
||
| Keyword names are case-insensitive and can include spaces. |
There was a problem hiding this comment.
| Keyword names are case-insensitive and can include spaces. | |
| Keyword names are case-insensitive and can include single spaces. |
| ```robotframework | ||
| *** Test Cases *** | ||
| Embedded and normal arguments | ||
| Given the user is on the pet selection page | ||
| When the user adds 2 cat fish | ||
| And the user sets 3 dogs | ||
| And the user removes 1 dogs | ||
| Then the number of cat fish should be 2 | ||
| And the number of dogs should be count=2 | ||
|
|
||
| *** Keywords *** | ||
| the number of ${animals} should be | ||
| [Arguments] ${count} | ||
| ${current_count} Get Animal Count ${animals} | ||
| Should Be Equal As Numbers ${current_count} ${count} | ||
|
|
||
| the user ${action} | ||
| [Arguments] ${amount} ${animal} | ||
| IF '${action}' == 'adds' | ||
| Add Items To List animal_list ${animal} ${amount} | ||
| ELSE IF '${action}' == 'removes' | ||
| Remove Items From List animal_list ${animal} ${amount} | ||
| ELSE IF '${action}' == 'sets' | ||
| Set Amount To List animal_list ${animal} ${amount} | ||
| ELSE | ||
| Skip Test skipped due to invalid action | ||
| END | ||
| ``` |
There was a problem hiding this comment.
This test fails:
Keyword 'the user $(action)' expected 2 arguments, got 0.
| | `${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.
I would suggest to use a consistent style for all the variable names:
${EXECDIR}${EXEC DIR}${EXEC_DIR}
This PR is there to make comments to the syllabus directly.