1## Features of OpenBMC Test Automation ##
2
3**Interface Feature List**
4* REST
5* DMTF Redfish
6* Out-of-band IPMI
7* SSH to BMC and Host OS
8
9**Key Feature List**
10* Power on/off
11* Reboot Host
12* Reset BMC
13* Code update BMC and host
14* Power management
15* Fan controller
16* HTX bootme
17* XCAT execution
18* Network
19* IPMI support (generic and DCMI compliant)
20* Factory reset
21* RAS (Reliability, availability and serviceability)
22* Web UI testing
23* IO storage and EEH (Enhanced Error Handling) testing
24* Secure boot
25* SNMP (Simple Network Management Protocol)
26* Remote Logging via Rsyslog
27* LDAP (Lightweight Directory Access Protocol)
28* Certificate
29
30**Debugging Supported List**
31* SOL collection
32* FFDC collection
33* Error injection from host
34
35## Installation Setup Guide ##
36* [Robot Framework Install Instruction](https://github.com/robotframework/robotframework/blob/master/INSTALL.rst)
37
38* Miscellaneous
39Packages required to be installed for OpenBmc Automation.
40Install the packages and it's dependencies via `pip`
41
42    REST base packages:
43    ```
44    $ pip install -U requests
45    $ pip install -U robotframework-requests
46    $ pip install -U robotframework-httplibrary
47    ```
48
49    Python redfish library packages:
50    For more detailed intstructions see [python-redfish-library](https://github.com/DMTF/python-redfish-library)
51    ```
52    $ pip install redfish
53    ```
54
55    SSH and SCP base packages:
56    For more detailed installation instructions see [robotframework-sshlibrary](https://pypi.python.org/pypi/robotframework-sshlibrary)
57    ```
58    $ pip install robotframework-sshlibrary
59    $ pip install robotframework-scplibrary
60    ```
61
62    Installing tox:
63    ```
64    $ pip install -U tox
65    ```
66
67If using Python 3.x, use the corresponding `pip3` to install packages.
68
69## OpenBMC Test Development ##
70
71These documents contain details on developing OpenBMC test code and debugging.
72
73 - [MAINTAINERS](https://github.com/openbmc/docs/blob/master/MAINTAINERS): OpenBMC code maintainers information.
74 - [CONTRIBUTING.md](CONTRIBUTING.md): Coding guidelines.
75 - [REST-cheatsheet.md](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md): Quick reference for some common
76   curl commands required for testing.
77 - [README.md](https://github.com/openbmc/phosphor-webui/blob/master/README.md): Web UI setup reference.
78 - [Tools.md](Tools.md): Reference information for helper tools.
79
80## Testing Setup Steps ##
81
82To verify the installation setup is completed and ready to execute.
83
84* Download the openbmc-test-automation repository:
85    ```
86    $ git clone https://github.com/openbmc/openbmc-test-automation
87    $ cd openbmc-test-automation
88    ```
89* Execute basic setup test run:
90    ```
91    $ robot -v OPENBMC_HOST:xx.xx.xx.xx templates/test_openbmc_setup.robot
92    ```
93    where xx.xx.xx.xx is the BMC hostname or IP.
94
95## Test Layout ##
96
97There are several sub-directories within the openbmc-test-automation base which
98contain test suites, tools, templates, etc. These sub-directories are
99classified as follows:
100
101`tests/`: Contains the general test cases for OpenBMC stack functional
102          verification.
103
104`extended/`: Contains test cases for boot testing, network testing,
105             code update testing etc.
106
107`systest/`: Contains test cases for HTX bootme, IO storage and EEH testing.
108
109`xcat/`: Contains test cases for XCAT automation.
110
111`gui/`: Contains test cases for web UI and security scanning tool automation.
112
113`mnfg/`: Contains test cases for factory reset (DHCP mode) and PGOOD testing.
114
115`network/`: Contains test cases for network testing. It covers IPv4 in static mode
116            and in DHCP mode.
117
118`snmp/`: Contains test cases for SNMP (Simple Network Management Protocol)
119         configuration testing.
120
121`remote_logging`: Contains test cases for remote logging via rsyslog.
122
123`openpower/ras/`: Contains test cases for RAS (Reliability, Availability and
124                  Serviceability) for an OpenPOWER system.
125
126`openpower/secureboot/`: Contains test cases for secure boot testing on a
127                         secure boot feature enabled OpenPOWER system only.
128
129`tools/`: Contains various tools.
130
131`templates/`: Contains sample code examples and setup testing.
132
133`test_list/`: Contains the argument files used for skipping test cases
134              (e.g "skip_test", "skip_test_extended", etc.) or
135              grouping them (e.g "HW_CI", "CT_basic_run", etc.).
136
137
138## Redfish Test Layout ##
139
140OpenBMC is moving steadily towards DTMF Redfish, which is an open industry standard
141specification and schema that meets the expectations of end users for simple,
142modern and secure management of scalable platform hardware.
143
144`redfish_test`: Contains test cases for DMTF Redfish-related feature supported
145                on OpenBMC.
146
147
148## Quickstart ##
149To run openbmc-automation first you need to install the prerequisite Python
150packages which will help to invoke tests through tox (Note that tox
151version 2.3.1 or greater is required) or via Robot CLI command.
152
153**Robot Command Line**
154
155* Execute all test suites for `tests/`:
156    ```
157    $ robot -v OPENBMC_HOST:xx.xx.xx.xx  tests
158    ```
159
160* Execute a test suite:
161    ```
162    $ robot -v OPENBMC_HOST:xx.xx.xx.xx  tests/test_basic_poweron.robot
163    ```
164
165* Initialize the following environment variables which will be used during testing:
166    ```
167    $ export OPENBMC_HOST=<openbmc machine ip address>
168    $ export OPENBMC_PASSWORD=<openbmc password>
169    $ export OPENBMC_USERNAME=<openbmc username>
170    $ export OPENBMC_MODEL=[./data/Witherspoon.py, ./data/Palmetto.py, etc]
171    $ export IPMI_COMMAND=<Dbus/External>
172    $ export IPMI_PASSWORD=<External IPMI password>
173    ```
174
175* For QEMU tests, set the following environment variables as well:
176    ```
177    $ export SSH_PORT=<ssh port number>
178    $ export HTTPS_PORT=<https port number>
179    ```
180
181* Run tests:
182    ```
183    $ tox -e tests
184    ```
185
186* How to run individual test:
187
188    One specific test:
189    ```
190    $ tox -e default -- --include Power_On_Test  tests/test_basic_poweron.robot
191    ```
192    No preset environment variables, default configuration for all supported
193    systems:
194    ```
195    $ OPENBMC_HOST=x.x.x.x tox -e default -- tests
196    ```
197    No preset environment variables, one test case from a test suite:
198    ```
199    $ OPENBMC_HOST=x.x.x.x tox -e default -- --include Power_On_Test tests/test_basic_poweron.robot
200    ```
201    No preset environment variables, the entire test suite:
202    ```
203    $ OPENBMC_HOST=x.x.x.x tox -e default -- tests
204    ```
205
206    No preset environment variables, the entire test suite excluding test
207    cases using argument file:
208    ```
209    $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/skip_test tests
210    ```
211
212    Exclude test list for supported systems:
213    ```
214    Palmetto:  test_lists/skip_test_palmetto
215    Witherspoon:  test_lists/skip_test_witherspoon
216    ```
217
218
219* Run IPMI tests:
220
221    Running only out-of-band IPMI tests:
222    ```
223    $ robot -v IPMI_COMMAND:External -v OPENBMC_HOST:x.x.x.x --argumentfile test_lists/witherspoon/skip_inband_ipmi tests/ipmi/
224    ```
225
226    Running only inband IPMI tests:
227    ```
228    $ robot -v IPMI_COMMAND:Inband -v OPENBMC_HOST:x.x.x.x -v OS_HOST:x.x.x.x -v OS_USERNAME:xxxx -v OS_PASSWORD:xxxx --argumentfile test_lists/witherspoon/skip_oob_ipmi tests/ipmi/
229    ```
230
231
232* Run GUI tests:
233
234    By default, GUI runs with Firefox browser and headless mode. Example with chrome browser and header mode:
235    ```
236    $ robot -v OPENBMC_HOST:x.x.x.x -v GUI_BROWSER:gc -v GUI_MODE:header gui/obmc_gui/test/
237    ```
238
239    Run GUI default CI test bucket:
240    ```
241    $ robot -v OPENBMC_HOST:x.x.x.x --argumentfile test_lists/BMC_WEB_CI gui/obmc_gui/test/
242    ```
243
244* Run LDAP tests:
245
246    Before using LDAP test functions, be sure appropriate LDAP user(s) and group(s) have been created on your LDAP server.
247    Note: There are multiple ways to create LDAP users / groups and all depend on your LDAP server.
248    One common way for openldap is ldapadd / ldapmodify refer https://linux.die.net/man/1/ldapadd
249    For ldapsearch, refer to "https://linux.die.net/man/1/ldapsearch".
250    Microsoft ADS: refer to  https://searchwindowsserver.techtarget.com/definition/Microsoft-Active-Directory-Domain-Services-AD-DS
251    ```
252    $ cd tests_ldap/
253    $ robot -v OPENBMC_HOST:x.x.x.x -v LDAP_SERVER_URI:<ldap(s)//LDAP Hostname / IP> -v LDAP_BIND_DN:<LDAP Bind DN> -v LDAP_BASE_DN:<LDAP Base DN> -v LDAP_BIND_DN_PASSWORD:<LDAP Bind password> -v LDAP_SEARCH_SCOPE:<LDAP search scope> -v LDAP_SERVER_TYPE:<LDAP server type> -v LDAP_USER:<LDAP user-id> -v LDAP_USER_PASSWORD:<LDAP PASSWORD> -v GROUP_NAME:<Group Name> -v GROUP_PRIVILEGE:<Privilege>  test_user_ldap_management.robot
254    ```
255
256* How to run CI and CT bucket test:
257
258    Default CI test bucket list:
259    ```
260    $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/HW_CI tests
261    ```
262
263    Default CI smoke test bucket list:
264    ```
265    $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/CT_basic_run tests
266    ```
267
268* Run extended tests:
269
270    For-loop test (default iteration is 10):
271    ```
272    $ robot -v OPENBMC_HOST:x.x.x.x -v OPENBMC_SYSTEMMODEL:xxxxxx -v ITERATION:n -v LOOP_TEST_COMMAND:xxxxxx extended/full_suite_regression.robot
273    ```
274
275    Example using tox testing a test suite for 5 iterations "witherspoon":
276    ```
277    OPENBMC_HOST=x.x.x.x  LOOP_TEST_COMMAND="tests/test_fw_version.robot" ITERATION=5 OPENBMC_SYSTEMMODEL=witherspoon tox -e witherspoon -- ./extended/full_suite_regression.robot
278    ```
279
280**Jenkins jobs tox commands**
281* HW CI tox command:
282    ```
283    $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/HW_CI tests
284    ```
285
286## Code Update ##
287
288Currently supported BMC and PNOR update formats are UBI and non-UBI.
289For code update information, please refer to [code-update.md](https://github.com/openbmc/docs/blob/master/code-update/code-update.md)
290
291
292* UBI Format *
293
294    For BMC code update, download the system type *.ubi.mdt.tar image from
295    https://openpower.xyz/job/openbmc-build/ and run as follows:
296
297    For Witherspoon system:
298    ```
299    $ cd extended/code_update/
300    $ robot -v OPENBMC_HOST:x.x.x.x -v IMAGE_FILE_PATH:<image path>/obmc-phosphor-image-witherspoon.ubi.mtd.tar --include REST_BMC_Code_Update  bmc_code_update.robot
301    ```
302
303    For host code update, download the system type *.pnor.squashfs.tar image
304    from https://openpower.xyz/job/openpower-op-build/ and run as follows:
305
306    For Witherspoon system:
307    ```
308    $ cd extended/code_update/
309    $ robot -v OPENBMC_HOST:x.x.x.x -v IMAGE_FILE_PATH:<image path>/witherspoon.pnor.squashfs.tar --include REST_Host_Code_Update  host_code_update.robot
310    ```
311
312* Non-UBI Format *
313
314    For BMC code update, download the system type *all.tar image from
315    https://openpower.xyz/job/openbmc-build/ and run as follows:
316
317    For a Zaius system:
318    ```
319    $ cd extended/code_update/
320    $ robot -v OPENBMC_HOST:x.x.x.x -v FILE_PATH:<image path>/zaius-<date time>.all.tar --include Initiate_Code_Update_BMC update_bmc.robot
321    ```
322
323    For host code update, download the system type *.pnor from
324    https://openpower.xyz/job/openpower-op-build/ and run as follows:
325
326    For a Zaius system:
327    ```
328    $ cd extended/
329    $ robot -v OPENBMC_HOST:x.x.x.x -v PNOR_IMAGE_PATH:<image path>/zaius.pnor test_bios_update.robot
330    ```
331