Description:
There is a need to have a decorator through which user can specify cluster information like number of servers, moms, comms and clients etc. required for a particular test to run.

Forum: http://community.pbspro.org/t/pp-1281-new-decorator-in-ptl-using-which-user-can-provide-cluster-information-required-for-a-test/1050

Ticket: 

Interface: @requirements(num_servers=<number_of_servers>,num_moms=<number_of_moms>,num_comms=<number_of_comms>,num_clients=<number_of_clients>,no_mom_on_server=<Boolean>,no_comm_on_server=<Boolean>, no_comm_on_mom=<Boolean>)
Visibility: Public
Change Control: Stable
Synopsis: New interface to provide the cluster information required for particular testcase/testsuite.
Details:

• @requirements decorator is used to specify the cluster requirements for a given test case to run. It can be specified at test case or test suite level. This decorator function is called before the test setup of the test case runs. 
• This requirements decorator data is validated against the data passed to the param list (-p and --param-file) of pbs_benchpress
• In case where the requirements do not match with the data passed to param list of pbs_benchpress, the test execution is skipped using SkipTest().
• In case where the requirements match with the data passed to param list of pbs_benchpress, the test execution is continued.
• Keys and default values for decorator parameters are: 
  • num_servers=1
  • num_moms=1
  • num_comms=1
  • num_clients=1
  • no_mom_on_server=False (Which will imply that Server host should have a mom on it )
  • no_comm_on_server=False (Which will imply that Server host should have a comm on it)
  • no_comm_on_mom=True (Which will imply that comm should be on different host than mom i.e. a mom on non-server host)

This means with default configuration, test will intend to run on a single node.

• The test case level values of requirements decorator override the test suite level requirements values
• Currently this data including the flags no_mom_on_server, no_comm_on_server & no_comm_on_mom are applicable to all the servers in case of multiple server setup

Examples: 

• Case 1- Default requirements : Test needs a single Node with all daemons on same host.

• Case 2- Test requires 4 moms and 2 comms.
  • With 1 mom and 1 comm on server node: @requirements(num_moms=4, num_comms=2)
    • By default 'no_mom_on_server' and 'no_comm_on_server' are False and no_comm_on_mom is true, so cluster will consist of total 5 nodes which will look like:
      • Node1: Server, Sched, Mom, Comm
      • Node2: Mom
      • Node3: Mom
      • Node4: Mom
      • Node5: Comm
  • With no mom and comm on server node: @requirements(num_moms=4, num_comms=2, no_mom_on_server=True, no_comm_on_server=True)
    • By default no_comm_on_mom is true, so cluster will consist of total 7 nodes which will look like:
      • Node1: Server, Sched
      • Node2: Mom
      • Node3: Mom
      • Node4: Mom
      • Node5: Mom
      • Node6: Comm
      • Node7: Comm
  • With no mom and comm on server node and comm on mom node: @requirements(num_moms=4, num_comms=2, no_mom_on_server=True, no_comm_on_server=True, no_comm_on_mom=False)
    • Cluster will consist of total 5 nodes which will look like:
      • Node1: Server, Sched
      • Node2: Mom, Comm
      • Node3: Mom, Comm
      • Node4: Mom
      • Node5: Mom

• Case 3 - Test requires 3 moms without comms on the mom nodes:
  • With 1 mom and 1 comm on server node: @requirements(num_moms=3)
    • Cluster will consist of total 3 nodes
      • Node 1: server,sched,mom1 & comm
      • Node 2: mom2
      • Node 3: mom3

Note: Currently PTL supports specification of a single host for "client" parameter in pbs_benchpress command, i.e. name of the host on which the PBS client commands are to be run from. Hence, the specification of requirement of multiple clients for a given test case can be completely functional only after implementation of ticket PP-1327. As of now test execution of any test case that specifies num_clients as greater than one will be skipped.

Interface: PTLTestInfo._gen_ts_tree()
Visibility: Public
Change Control: Stable
Synopsis: Updating existing interface to add requirements information to testsuite's json tree, provided by @requirements decorator. Tools which run PTL, can make use of this information to form a multinode cluster.
Details:

• json test suite tree generated with info option of pbs_benchpress along with --gen-ts-tree (using PTLTestInfo._gen_ts_tree() method) will now include the requirements data mentioned for each test case
• this data is populated as value for a new key called 'requirements' under test case name hierarchy in the generated json tree
• for test cases without requirements decorator, default values of requirements are specified

Example: json tree of a test case with @requirements(num_moms=4) inside a test suite with @requirements(num_comms=2) at test suite level will look as below:

"test_submit_job": {
    "doc": "\n Test to submit a job\n ",
    "tags": [
        "smoke"
    ],
    "requirements": {
        "num_moms": 4,
        "no_comm_on_mom": true,
        "no_comm_on_server": false,
        "num_servers": 1,
        "no_mom_on_server": false,
        "num_comms": 2,
        "num_clients": 1
        },
    "numnodes": "5"
},