Merge "[ONOS-7529]: Update TestON Documentation (README.md in this case)"
diff --git a/README.md b/README.md
index 49ded69..ba7803a 100644
--- a/README.md
+++ b/README.md
@@ -1,132 +1,116 @@
-TestON, a testing infastructure by Paxterra and Open Networking Labs
+TestON: Testing Infastructure by Paxterra and Open Networking Foundation
=======================================
TestON is the testing platform that all the ONOS tests are being run on currently.
-Code Style
--------------
-At ON.Lab, we have adopted the [Mininet Python style](https://github.com/mininet/mininet/wiki/Mininet-Python-Style) for our drivers and testcases. The one exception is that TestON does not correctly parse multiline comments in testcases when the ending triple double quotes are on the same line as the comment. Therefore, in the testcases, the ending triple double quotes must be on it's own line.
+Visit the [ONOS System Testing Guide](https://wiki.onosproject.org/display/ONOS/System+Testing+Guide) on the ONOS Wiki for details about the repo, and our [TestON Contribution Guide](https://wiki.onosproject.org/display/ONOS/How+to+Contribute+to+System+Test?src=contextnavpagetreemode) for how to contribute.
-
-Setup
+Quick Setup
-------------
-0. Pull the git repo from gerrit or github(Read only mirror)
+1. Clone OnosSystemTest from ONOS Gerrit:
+ ```
$ git clone https://gerrit.onosproject.org/OnosSystemTest
+ ```
- or
+2. Run the installation script:
- $ git clone https://github.com/OPENNETWORKINGLAB/OnosSystemTest.git
-
-1. Run the install script
-
+ ```
$ cd OnosSystemTest/TestON
-
- $ install.sh
-
-
+ $ ./install.sh
+ ```
Dependencies
------------
-1. [ONOS](https://github.com/opennetworkinglab/onos) - The system under test
+- [ONOS](https://github.com/opennetworkinglab/onos) - The system being tested.
-2. [Mininet](https://github.com/mininet/mininet) - A Network Emulator. NOTE: Some driver functions rely on a modified version of Mininet. These functions are noted in the mininet driver file. To checkout this branch from your Mininet folder:
+- [Mininet](https://github.com/mininet/mininet) - A Network Emulator. NOTE: Some driver functions rely on a modified version of Mininet. These functions are noted in the Mininet driver file. Here's how to checkout this branch from the Mininet folder:
+ ```
$ git remote add jhall11 https://github.com/jhall11/mininet.git
-
$ git fetch jhall11
-
$ git checkout -b dynamic_topo remotes/jhall11/dynamic_topo
-
$ git pull
+ ```
- Note that you may need to run 'sudo make develop' if your mnexec.c file changed when switching branches.
+ Note that you may need to run ``sudo make develop`` if your ``mnexec.c`` file changed when switching branches.
-3. There are some python modules required by some test cases. These modules should be installed by running the install.sh script.
-
-4. Linc-OE - Some testcases use this to emulate optical devices
+- Linc-OE - Some testcases use this to emulate optical devices.
Requirements:
1. Erlang R15B, R16B, R17 - if possible please use R17
- $ sudo apt-get install erlang
+ ```
+ $ sudo apt-get install erlang
+ ```
2. libpcap-dev package if eth interfaces will be used
- $ sudo apt-get install libpcap-dev
+ ```
+ $ sudo apt-get install libpcap-dev
+ ```
Building and Running:
+ ```
$ git clone https://github.com/shivarammysore/LINC-Switch.git linc-oe
-
$ cd linc-oe
-
$ git checkout tags/oe-0.3
-
$ cp rel/files/sys.config.orig rel/files/sys.config
-
$ make rel
+ ```
-Configuration
-------------
-1. Config file at TestON/config/teston.cfg
+Tests
+-----------------------------------------------
- Change the file paths to the appropriate paths
+The tests are all located in ``TestON/tests/``.
+Each test has its own folder with the following files:
-2. The .topo file for each test
+- ``.py`` file:
- Must change the IPs/login/etc to point to the nodes you want to run on
+ - This defines the cases and sequence of events for the test.
+
+- ``.topo`` file:
+
+ - This defines all the components that TestON creates for that test and includes data such as IP address, login info, and device drivers.
+
+ - The components must be defined in this file to be used in the ``.py`` files.
+
+- ``.params`` file:
+
+ - Defines all the test-specific variables that are used by the test.
+
+ - NOTE: The variable `testcases` defines which testcases are run.
Running TestON
------------
-1. TestON must be ran from its bin directory
+1. TestON must be run from its bin directory:
+ ```
$ cd TestON/bin
+ ```
-2. Run the test
+2. To run a test:
- $ teston run SAMPstartTemplate_1node
+ ```
+ $ ./cli.py run SAMPstartTemplate_1node
+ ```
-The Tests
------------------------------------------------
+Code Style
+-------------
+At Open Networking Foundation, we have adopted the [Mininet Python Style](https://github.com/mininet/mininet/wiki/Mininet-Python-Style) formatting for our drivers and testcases. The one exception is that TestON does not correctly parse multiline comments in testcases when the ending triple double quotes are on the same line as the comment. Therefore, in the testcases, the ending triple double quotes must be on it's own line.
-The tests are all located it TestON/tests/
-Each test has its own folder with the following files:
-1. .ospk file (optional)
-
- - This is written in Openspeak, a word based language developed by Paxterra.
-
- - It defines the cases and sequence of events for the test
-
- - TestON will automatically generate the .py file based on the .ospk file if the .ospk file exists.
-
-2. .py file
-
- - This file serves the same exact function as the openspeak file.
-
- - It will only be used if there is NO .ospk file, so if you like python, delete or rename the .ospk file
-
-3. .topo file
-
- - This defines all the components that TestON creates for that test and includes data such as IP address, login info, and device drivers
-
- - The Components must be defined in this file to be uesd in the openspeak or python files.
-
-4. .params file
-
- - Defines all the test-specific variables that are used by the test.
-
- - NOTE: The variable `testcases` defines which testcases run when the test is ran.
Troubleshooting
-----------------------------------------------
-Here are a few things to check if it doesn't work
-1. Double check the topo file for that specific test the nodes must be able to run that specific component ( Mininet IP -> machine with mn installed)
+- Double check the topo file for that specific test the nodes must be able to run that specific component (Mininet IP is targetting the machine with Mininet installed).
-2. Enable passwordless logins between your nodes and the TestON node.
+- Enable passwordless logins between your nodes and the TestON node.
+
+- Visit our [FAQ/Troubleshooting](https://wiki.onosproject.org/display/ONOS/TestON+FAQs) page on the ONOS Wiki.
diff --git a/TestON/README.md b/TestON/README.md
index 5335503..b97417c 100644
--- a/TestON/README.md
+++ b/TestON/README.md
@@ -1,24 +1,11 @@
Welcome to TestON !
-------------------
-[](#TestON)
-
-Introduction
--------------
TestON is a solution that aims to interact with OpenFlow/SDN components and automate the functionality of the components.
-TestON is an end to end automation solution for testing the Openflow/SDN components.
+TestON is an end to end automation solution for testing the Openflow/SDN components
run across various components in an OpenFlow topology. This solution
-aims to provide an automation framework, that is not just exhaustive in
+aims to provide an automation framework that is not just exhaustive in
coverage, but also makes it easy to debug and author scripts.
-It allows for authoring scripts in OpenSpeak (plain English) format and can be run standalone from the command line.
-
-
-Note:
------
-
-Please change the params parser file path and Parser name in ~/config/ofa.cfg
-
-
Test Launch
------------
@@ -28,40 +15,35 @@
* A Linux 2.6.26 or greater kernel compiled with network namespace support
enabled (see INSTALL for additional information.)
-* python 2.6 or higher versions.
+* Python 2.6 or higher versions.
-* Install python package configObj. It can be installed as :
+* Install python package ``configObj``. It can be installed as :
- openflow@ETH-Tutorial:~$ sudo pip install configObj
+ ```
+ $ sudo pip install configObj
+ ```
+ How to launch a test:
-* Finally ,launching of test:
+ * Navigate to the ``bin/`` directory which
+ resides in the ``TestON/`` directory:
-* TestON providing two options to launch the test.
+ ```
+ $ ./cli.py
+ teston> run SAMPstartTemplate_1node
+ ```
- 1 .Console based :
+ or
- * Launching of test must be from "bin" directory which
-
- resides into "TestON-master" directory as following:
-
- sdn@test-station:~/TestON/bin$ ./cli.py
- teston>run MininetTest
-
- 2. TAI (Test Authoring Interface) UI based :
-
- * Will provide TAI stand-alone application soon, now user can get the raw code from the TAI directory.
-
- User can launch the test from TAI-UI by clicking the Run Button in tool-bar.
-
-[](#RunTest)
+ ```
+ $ ./cli.py run SAMPstartTemplate_1node
+ ```
Examples
--------
-For more examples, refer 'examples' directory.
-Please find the below link for examples:
- https://github.com/opennetworkinglab/OnosSystemTest/tree/master/TestON/examples
+For more examples, refer to the ``TestON/tests/SAMP/`` directory.
+Check out the [ONOS Wiki](https://wiki.onosproject.org/) for [guides](https://wiki.onosproject.org/display/ONOS/System+Testing+Guide) in creating a test.