xref: /openbmc/openbmc-test-automation/docs/redfish_coding_guidelines.md (revision e80bf773c6b005127429abf61be5fe48b1e0d621) 
1# Redfish Coding Guidelines
2
3- For robot programs wishing to run Redfish commands, include the following in
4  your robot file:
5
6  ```
7  *** Settings ***
8
9  Resource                    bmc_redfish_resource.robot
10  ```
11
12- This git repository has some redfish wrapper modules:
13  - [redfish_plus.py](../lib/redfish_plus.py)
14  - [bmc_redfish.py](../lib/bmc_redfish.py)
15  - [bmc_redfish_utils.py](../lib/bmc_redfish_utils.py)
16  - Redfish wrapper module features:
17
18    For all Redfish REST requests (get, head, post, put, patch, delete):
19    - Support for python-like strings for all arguments which allows callers to
20      easily specify complex arguments such as lists or dictionaries.
21
22      So instead of coding this:
23
24      ```
25          ${ldap_type_dict}=  Create Dictionary  ServiceEnabled=${False}
26          ${body}=  Create Dictionary  ${LDAP_TYPE}=${ldap_type_dict}
27          Redfish.Patch  ${REDFISH_BASE_URI}AccountService  body=${body}
28      ```
29
30      You can do it in one fell swoop like this:
31
32      ```
33          Redfish.Patch  ${REDFISH_BASE_URI}AccountService  body={'${LDAP_TYPE}': {'ServiceEnabled': ${False}}}
34      ```
35
36    - Support for **valid_status_codes** argument and auto-failure:
37
38      As mentioned above, this argument may be either an actual robot/python
39      list or it may be a string value which python can translate into a list.
40
41      The default value is [${HTTP_OK}].
42
43      This means that the Redfish REST request will fail **automatically** if
44      the resulting status code is not found in the valid_status_codes list.
45
46      So instead of having to do this:
47
48      ```
49          ${resp}=  Redfish.Get  ${EVENT_LOG_URI}Entries
50          Should Be Equal As Strings  ${resp.status_code}  ${HTTP_OK}
51      ```
52
53      You can simply do this:
54
55      ```
56          ${resp}=  Redfish.Get  ${EVENT_LOG_URI}Entries
57      ```
58
59      If, for some reason, you **expect** your command to fail, you can specify
60      the expected status code or codes:
61
62      ```
63      Redfish.Patch  ${REDFISH_BASE_URI}UpdateService  body={'ApplyTime' : 'Invalid'}  valid_status_codes=[${HTTP_BAD_REQUEST}]
64      ```
65
66  - Login defaults for path, username and password are
67    https://${OPENBMC_HOST},
68    ${OPENBMC_USERNAME}, ${OPENBMC_PASSWORD}.
69  - Many utility functions are available. Examples:;
70    - get_properties
71    - get_attributes
72    - get_session_info
73    - list_request
74    - enumerate_request
75
76# Rules for use of Redfish.Login and Redfish.Logout
77
78It is desirable to avoid excessive redfish logins/logouts for the following
79reasons:
80
81- It simplifies the code base.
82- It allows calling keywords and testcases to keep control over login parameters
83  like USERNAME, PASSWORD, etc. Consider the following example:
84
85  ```
86  # Login to redfish with non-standard username/password.
87  Redfish.Login  ${LDAP_USER}  ${LDAP_USER_PASSWORD}
88  # Run 'Some Keyword' while logged in as ${LDAP_USER}/${LDAP_USER_PASSWORD}.
89  Some Keyword
90  ```
91
92  If 'Some Keyword' in the example above does its own Redfish.Login, it will
93  thwart the stated purpose of the caller.
94
95**Rules:**
96
97- Login should be done once in Suite Setup:
98
99  ```
100  *** Keywords ***
101  Suite Setup Execution
102      Redfish.Login
103  ```
104
105- Logout should be done once in Suite Teardown:
106  ```
107  *** Keywords ***
108  Suite Teardown Execution
109      Redfish.Logout
110  ```
111- As a result of the first two rules, all keywords and testcases that call upon
112  redfish functions (e.g. Redfish.Get, Redfish.Patch, etc.) have a right to
113  expect that login/logout have already been handled. Therefore, such keywords
114  and testcases should NOT do logins and logouts themselves.
115- There may be exceptions to the above but they require justification (e.g. a
116  test whose purpose is to verify that it can login with an **alternate**
117  username, etc.).
118- Any keyword or test case which breaks the above rules is responsible for
119  setting things right (i.e. back to a logged in state).
120
121# Rules for use of data/variables.py
122
123Avoid defining variables in data/variables.py for Redfish URIs.
124
125There's no obvious benefit to using such variables. Conversely, with literal
126values, it is much easier for the programmer to interpret the code.
127
128Consider the following example.
129
130Here's an excerpt from data/variables.py:
131
132```
133# Redfish variables.
134REDFISH_BASE_URI = '/redfish/v1/'
135...
136REDFISH_ACCOUNTS = 'AccountService/Accounts/'
137REDFISH_ACCOUNTS_URI = REDFISH_BASE_URI + REDFISH_ACCOUNTS
138```
139
140And here is a corresponding Robot code example:
141
142```
143    # Rather than coding this:
144    Redfish.Delete  ${REDFISH_ACCOUNTS_URI}user_user
145
146    # Code this:
147    Redfish.Delete  /redfish/v1/AccountService/Accounts/user_user
148```
149