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* Secure boot
24* SNMP (Simple Network Management Protocol)
25* Remote Logging via Rsyslog
26* LDAP (Lightweight Directory Access Protocol)
27* Certificate
28* Local User Management(Redfish/IPMI)
29* DateTime
30* Event Logging
31
32**Debugging Supported List**
33* SOL collection
34* FFDC collection
35* Error injection from host
36
37## Installation Setup Guide ##
38* [Robot Framework Install Instruction](https://github.com/robotframework/robotframework/blob/master/INSTALL.rst)
39
40* Miscellaneous
41Packages required to be installed for OpenBmc Automation.
42Install the packages and it's dependencies via `pip`
43
44    REST base packages:
45    ```
46    $ pip install -U requests
47    $ pip install -U robotframework-requests
48    $ pip install -U robotframework-httplibrary
49    ```
50
51    Python redfish library packages:
52    For more detailed intstructions see [python-redfish-library](https://github.com/DMTF/python-redfish-library)
53    ```
54    $ pip install redfish
55    ```
56
57    SSH and SCP base packages:
58    For more detailed installation instructions see [robotframework-sshlibrary](https://pypi.python.org/pypi/robotframework-sshlibrary)
59    ```
60    $ pip install robotframework-sshlibrary
61    $ pip install robotframework-scplibrary
62    ```
63
64    Installing tox:
65    ```
66    $ pip install -U tox
67    ```
68
69If using Python 3.x, use the corresponding `pip3` to install packages.
70
71## OpenBMC Test Development ##
72
73These documents contain details on developing OpenBMC test code and debugging.
74
75 - [MAINTAINERS](MAINTAINERS): OpenBMC test code maintainers information.
76 - [CONTRIBUTING.md](CONTRIBUTING.md): Coding guidelines.
77 - [REST-cheatsheet.md](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md): Quick reference for some common
78   curl commands required for legacy REST testing.
79 - [REDFISH-cheatsheet.md](https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md): Quick reference for some common
80   curl commands required for redfish testing.
81 - [README.md](https://github.com/openbmc/phosphor-webui/blob/master/README.md): Web UI setup reference.
82 - [Corporate CLA and Individual CLA](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes-via-gerrit-server): Submitting changes via Gerrit server
83
84## OpenBMC Test Documentation ##
85
86 - [Tools](https://github.com/openbmc/openbmc-test-automation/blob/master/docs/openbmc_test_tools.md): Reference information for helper tools.
87 - [Code Update](https://github.com/openbmc/openbmc-test-automation/blob/master/docs/code_update.md): Currently supported BMC and PNOR update.
88 - [Certificate Generate](https://github.com/openbmc/openbmc-test-automation/blob/master/docs/certificate_generate.md): Steps to create and install CA signed certificate.
89
90## Testing Setup Steps ##
91
92To verify the installation setup is completed and ready to execute.
93
94* Download the openbmc-test-automation repository:
95    ```
96    $ git clone https://github.com/openbmc/openbmc-test-automation
97    $ cd openbmc-test-automation
98    ```
99* Execute basic setup test run:
100    ```
101    $ robot -v OPENBMC_HOST:xx.xx.xx.xx templates/test_openbmc_setup.robot
102    ```
103    where xx.xx.xx.xx is the BMC hostname or IP.
104
105## Test Layout ##
106
107There are several sub-directories within the openbmc-test-automation base which
108contain test suites, tools, templates, etc. These sub-directories are
109classified as follows:
110
111`tests/`: Contains the general test cases for OpenBMC stack functional
112          verification. The "tests" subdirectory uses legacy REST and will be
113          deprecated at some point and therefore no longer supported.
114
115`extended/`: Contains test cases for boot testing, code update testing using legacy REST, etc.
116
117`systest/`: Contains test cases for HTX bootme testing.
118
119`xcat/`: Contains test cases for XCAT automation.
120
121`gui/`: Contains test cases for web UI and security scanning tool automation.
122
123`snmp/`: Contains test cases for SNMP (Simple Network Management Protocol)
124         configuration testing.
125
126`openpower/ras/`: Contains test cases for RAS (Reliability, Availability and
127                  Serviceability) for an OpenPOWER system.
128
129`openpower/secureboot/`: Contains test cases for secure boot testing on a
130                         secure boot feature enabled OpenPOWER system only.
131
132`tools/`: Contains various tools.
133
134`templates/`: Contains sample code examples and setup testing.
135
136`test_list/`: Contains the argument files used for skipping test cases
137              (e.g "skip_test", "skip_test_extended", etc.) or
138              grouping them (e.g "HW_CI", "CT_basic_run", etc.).
139
140
141## Redfish Test Layout ##
142
143OpenBMC is moving steadily towards DTMF Redfish, which is an open industry standard
144specification and schema that meets the expectations of end users for simple,
145modern and secure management of scalable platform hardware.
146
147`redfish/`: Contains test cases for DMTF Redfish-related feature supported on OpenBMC.
148
149`redfish/extended/`: Contains test cases for combined legacy REST and DMTF Redfish-related
150                     feature supported on OpenBMC.
151
152
153
154## Quickstart ##
155To run openbmc-automation first you need to install the prerequisite Python
156packages which will help to invoke tests through tox (Note that tox
157version 2.3.1 or greater is required) or via Robot CLI command.
158
159**Robot Command Line**
160
161* Execute all test suites for `tests/`:
162    ```
163    $ robot -v OPENBMC_HOST:xx.xx.xx.xx  tests
164    ```
165
166* Execute a test suite:
167    ```
168    $ robot -v OPENBMC_HOST:xx.xx.xx.xx  tests/test_basic_poweron.robot
169    ```
170
171* Initialize the following environment variables which will be used during testing:
172    ```
173    $ export OPENBMC_HOST=<openbmc machine ip address>
174    $ export OPENBMC_PASSWORD=<openbmc password>
175    $ export OPENBMC_USERNAME=<openbmc username>
176    $ export OPENBMC_MODEL=[./data/Witherspoon.py, ./data/Palmetto.py, etc]
177    $ export IPMI_COMMAND=<Dbus/External>
178    $ export IPMI_PASSWORD=<External IPMI password>
179    ```
180
181* For QEMU tests, set the following environment variables as well:
182    ```
183    $ export SSH_PORT=<ssh port number>
184    $ export HTTPS_PORT=<https port number>
185    ```
186
187* Run tests:
188    ```
189    $ tox tests
190    ```
191
192* How to run individual test:
193
194    One specific test:
195    ```
196    $ tox -e default -- --include Power_On_Test  tests/test_basic_poweron.robot
197    ```
198    No preset environment variables, default configuration for all supported
199    systems:
200    ```
201    $ OPENBMC_HOST=x.x.x.x tox -e default -- tests
202    ```
203    No preset environment variables, one test case from a test suite:
204    ```
205    $ OPENBMC_HOST=x.x.x.x tox -e default -- --include Power_On_Test tests/test_basic_poweron.robot
206    ```
207    No preset environment variables, the entire test suite:
208    ```
209    $ OPENBMC_HOST=x.x.x.x tox -e default -- tests
210    ```
211
212    No preset environment variables, the entire test suite excluding test
213    cases using argument file:
214    ```
215    $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/skip_test tests
216    ```
217
218    Exclude test list for supported systems:
219    ```
220    Palmetto:  test_lists/skip_test_palmetto
221    Witherspoon:  test_lists/skip_test_witherspoon
222    ```
223
224
225* Run IPMI tests:
226
227    Running only out-of-band IPMI tests:
228    ```
229    $ robot -v IPMI_COMMAND:External -v OPENBMC_HOST:x.x.x.x --argumentfile test_lists/witherspoon/skip_inband_ipmi tests/ipmi/
230    ```
231
232    Running only inband IPMI tests:
233    ```
234    $ 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/
235    ```
236
237
238* Run GUI tests:
239
240    By default, GUI runs with Firefox browser and headless mode. Example with chrome browser and header mode:
241    ```
242    $ robot -v OPENBMC_HOST:x.x.x.x -v GUI_BROWSER:gc -v GUI_MODE:header gui/test/
243    ```
244
245    Run GUI default CI test bucket:
246    ```
247    $ robot -v OPENBMC_HOST:x.x.x.x --argumentfile test_lists/BMC_WEB_CI gui/test/
248    ```
249
250* Run LDAP tests:
251
252    Before using LDAP test functions, be sure appropriate LDAP user(s) and group(s) have been created on your LDAP server.
253    Note: There are multiple ways to create LDAP users / groups and all depend on your LDAP server.
254    One common way for openldap is ldapadd / ldapmodify refer https://linux.die.net/man/1/ldapadd
255    For ldapsearch, refer to "https://linux.die.net/man/1/ldapsearch".
256    Microsoft ADS: refer to  https://searchwindowsserver.techtarget.com/definition/Microsoft-Active-Directory-Domain-Services-AD-DS
257
258   Note: Currently, LDAP test automation for Redfish API is in progress. The format to invoke LDAP test is as follows:
259    ```
260    $ cd redfish/account_service/
261    $ 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_ldap_configuration.robot
262    ```
263
264* How to run CI and CT bucket test:
265
266    Default CI test bucket list:
267    ```
268    $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/HW_CI tests
269    ```
270
271    Default CI smoke test bucket list:
272    ```
273    $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/CT_basic_run tests
274    ```
275
276* Run extended tests:
277
278    For-loop test (default iteration is 10):
279    ```
280    $ 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
281    ```
282
283    Example using tox testing a test suite for 5 iterations "witherspoon":
284    ```
285    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
286    ```
287
288**Jenkins jobs tox commands**
289* HW CI tox command:
290    ```
291    $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/HW_CI tests
292    ```
293