Skip to content

Commit b230689

Browse files
RobertG699d-biehl
RobertG699
authored and
d-biehl
committed
docs: updated config page
1 parent 35f14f9 commit b230689

File tree

5 files changed

+206
-12
lines changed

5 files changed

+206
-12
lines changed

‎docs/02_get_started/configuration.md‎

Lines changed: 206 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,208 @@
11
# Configuration
22

3-
- [ ] What is a `robot.toml` file
4-
- [ ] How to use `robot.toml`
5-
- [ ] in vscode
6-
- [ ] on command line
7-
- [ ] in other editors/CI Pipelines, ...
8-
- [ ] robot.toml
9-
- [ ] RobotCode settings
10-
- [ ] RobotFramework Settings
11-
- [ ] Profiles
12-
- [ ] Define profiles
13-
- [ ] override vs expand settings
14-
- [ ] Use profiles
3+
## Introducing the `robot.toml` file
4+
The `robot.toml` file offers an alternative way of setting up your project in VS Code. Usually, those settings would be done via the `settings.json` file, doing so comes though at the cost of several limitations and inconveniences. Using `robot. toml` alleviates many of those by:
5+
- providing a simpler way of defining project settings in one file
6+
- creating a file that can be easily shared and uploaded to a git repository
7+
- removing the need to create an argument file
8+
- simplifying the command line execution
9+
- allowing to define multiple, easily expandable, profiles
10+
11+
Please make sure that you have installed the **Even Better TOML** extension before attempting to work with `robot.toml`.
12+
13+
The following documentation serves as a quick introduction on how to use the `robot.toml` file and will cover only the essentials. For a complete documentation, please refer to the [Robot Framework User Guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html "Robot Framework User Guide").
14+
15+
## Settings configuration
16+
Using the `robot.toml` file, we can configure a wide range of settings for our project. The example below shows how we can setup the output directory, language and global project variables. In toml, `[variables]` is a tabular setting, meaning it can store multiple name-value pairs.
17+
```toml
18+
output-dir = "output"
19+
languages = ["english"]
20+
21+
[variables]
22+
NAME = "Tim"
23+
AGE = "25"
24+
MAIL = "hotmail.de"
25+
```
26+
You can access a full list of available setting by excetuting `robot --help` in the CLI.
27+
28+
## Profiles
29+
Profiles allow you to store multiple configurations, in an easily accessible way. This can be useful if for example you need a different set of configurations, for testing on multiple platforms. Profiles are easily expandable and can be easily shared between developers by simply providing them the robot.toml file.
30+
### Defining profiles
31+
You can define a profile with `[profiles.YOUR_PROFILE_NAME]`. Follow it up with the settings that you want to configure for that particular profile. For tabular settings like `[variables]` you will need to create a separate entry using `[profiles.YOUR_PROFILE_NAME.variables]`. Your profiles will use any global configuration, that has not been defined within the profile. In example below, dev2 will use English as the language and *output* as the output directory.
32+
```toml
33+
output-dir = "output"
34+
languages = ["english"]
35+
36+
[variables]
37+
NAME = "Tim"
38+
AGE = "25"
39+
MAIL = "hotmail.de"
40+
41+
[profiles.dev1]
42+
output-dir = "dev1output"
43+
languages = ["german"]
44+
45+
[profiles.dev1.variables]
46+
NAME = "Lisa"
47+
AGE = "32"
48+
MAIL = "web.de"
49+
50+
[profiles.dev2.variables]
51+
NAME = "Andrew"
52+
AGE = "19"
53+
MAIL = "gmail.com"
54+
55+
[profiles.dev3]
56+
output-dir = "dev3output"
57+
```
58+
59+
### Overriding and extending settings
60+
Tabular settings like `[variables]` can be either overridden or expanded. In the example below, dev1 and dev2 are overriding `[variables]`. Override will prevent dev1 and dev2 from using any of the values defined in lines 4-7. This means that dev2 will not use `NAME = "Tim"` defined in line 5 but instead whatever is defined in the relevant .robot files.
61+
```toml
62+
output-dir = "output"
63+
languages = ["english"]
64+
65+
[variables]
66+
NAME = "Tim"
67+
AGE = "25"
68+
MAIL = "hotmail.de"
69+
70+
[profiles.dev1.variables]
71+
NAME = "Lisa"
72+
AGE = "32"
73+
MAIL = "web.de"
74+
75+
[profiles.dev2.variables]
76+
AGE = "19"
77+
MAIL = "gmail.com"
78+
```
79+
In order to change only selected values or add new ones, the 'extend-' prefix is needed. In the example below, dev2 will still use `NAME` and `AGE` defined in lines 2 and 3.
80+
```toml
81+
[variables]
82+
NAME = "Tim"
83+
AGE = "25"
84+
MAIL = "hotmail.de"
85+
86+
[profiles.dev2.extend-variables]
87+
MAIL = "gmail.com"
88+
LOCATION = "Berlin"
89+
```
90+
91+
### Inheriting and merging profiles
92+
Profiles can inherit from an already existing profile.
93+
```toml
94+
[profiles.dev3]
95+
output-dir = "dev3output"
96+
97+
[profiles.inheritedFromDev3]
98+
inherits = ["dev3"]
99+
languages = ["german"]
100+
```
101+
It is also possible to inherit from multiple profiles.
102+
103+
```toml
104+
[profiles.dev1]
105+
output-dir = "dev1output"
106+
languages = ["german"]
107+
108+
[profiles.dev1.variables]
109+
NAME = "Lisa"
110+
AGE = "32"
111+
MAIL = "web.de"
112+
113+
[profiles.dev3]
114+
output-dir = "dev3output"
115+
116+
[profiles.dev1and3]
117+
inherits = ["dev1, dev3"]
118+
```
119+
If a variable is present in multiple of the inherited profiles, the value of that variable will be the one, present in the last relevant inherited profile. In the example above, the value of `output-dir` for the dev1and2 profile, will be "dev3output".
120+
### Profile management
121+
122+
#### Selecting profiles
123+
You can select a profile to work with, by entering "RobotCode: Select Configuration Profiles" in the command palette (ctrl+shift+p).
124+
![Select Profile1](./../images/config%20images/toml-profiles-command-selection.PNG)
125+
Should you select more than one profile, a merged version of those profiles will be executed.
126+
Alternatively, you can select a profile to run or debug with, by clicking on the buttons, marked in the image below.
127+
![Select Profile2](./../images/config%20images/config_selec_buttons.PNG)
128+
Using this method however, does not allow you to select multiple profiles at once.
129+
#### Default profiles
130+
It is possible to select a list of default profiles, using the `default-profiles` option. Those profiles will be selected by default, if no other profile has been selected for execution.
131+
Should you select more than one default profile, a merged version of those profiles will be executed.
132+
```toml
133+
default-profiles = ["dev1", "dev2"]
134+
135+
[profiles.dev1.variables]
136+
NAME = "Lisa"
137+
AGE = "32"
138+
MAIL = "web.de"
139+
140+
[profiles.dev2.variables]
141+
AGE = "19"
142+
MAIL = "gmail.com"
143+
144+
[profiles.dev3.variables]
145+
MAIL = "hotmail.com"
146+
```
147+
#### Hiding profiles
148+
If, for whatever reason, you wish for individual profiles to not be displayed as selectable options, you can hide them by using the `hidden` option.
149+
```toml
150+
[profiles.dev1]
151+
hidden = true
152+
```
153+
It is also possible to hide a profile based on user defined conditions, using python expressions.
154+
```toml
155+
[profiles.dev1]
156+
hidden.if = "platform.system()=='Windows'"
157+
```
158+
Hidden profiles can be still merged and inherited from.
159+
#### Enabling profiles
160+
Similar to hiding, profiles can be also disabled using the `enabled` option.
161+
```toml
162+
[profiles.dev1]
163+
enabled = false
164+
```
165+
It is also possible to enable or disable a profile based on user defined conditions, using python expressions.
166+
```toml
167+
[profiles.dev1]
168+
enabled.if = "platform.system()=='Windows'"
169+
```
170+
Disabled profiles cannot be merged or inherited from.
171+
172+
### Test Execution
173+
It is possible to run tests from the CLI. TEXT ABOUT OTHER FORMS OF EXECUTION.
174+
In order to execute tests using the CLI, you will need to install the `robotcode-runner` pip package and add it to your requirements.txt.
175+
176+
#### Executing tests
177+
Here are some of the most common ways, to execute tests via the CLI.
178+
179+
<details closed>
180+
<summary>robotcode robot PATH</summary>
181+
Executes all tests (including in subfolders) within a given location. This command can be also executed with the command <span style="color:lightblue">robotcode robot</span> robot, if you add <span style="color:lightblue">paths = "TESTFILE_LOC"</span> to your robot.toml file.
182+
</details>
183+
184+
<details closed>
185+
<summary>robotcode robot -t "TEST_CASE_NAME"<</summary>
186+
Executes the test case called <span style="color:lightblue">TEST_CASE_NAME</span>.
187+
</details>
188+
189+
<details closed>
190+
<summary>robotcode -p PROFILE_NAME robot PATH</summary>
191+
Executes all tests (including in subfolders) within a given location, with the selected profile.
192+
</details>
193+
194+
<details closed>
195+
<summary>robotcode -p PROFILE_NAME_1 -p PROFILE_NAME_2 robot PATH</summary>
196+
Executes all tests (including in subfolders) within a given location, with a merged version the selected profiles.
197+
</details>
198+
199+
<details closed>
200+
<summary>robotcode -p PROFILE_NAME -v NAME:Carl robot PATH</summary>
201+
Executes all tests (including in subfolders) within a given location. Changes the value of the variable <span style="color:lightblue">NAME</span> to <span style="color:lightblue">Carl</span>.
202+
</details>
203+
204+
<details closed>
205+
<summary>robotcode robot -i TAG_NAME</summary>
206+
Executes all tests with a given tag. Tags can be assigned either globally in the settings or individually for each test case.
207+
<IMG src="./../images/config%20images/tags_robot.PNG"/>
208+
</details>

‎docs/images/config images/config_selec_buttons.PNG‎

18.9 KB
Loading

‎docs/images/config images/profiles-dropdown-selection.PNG‎

99.1 KB
Loading

‎docs/images/config images/tags_robot.PNG‎

7.43 KB
Loading

‎docs/images/config images/toml-profiles-command-selection.PNG‎

95 KB
Loading

0 commit comments

Comments
 (0)