From f1ea9802e5620e8c13adbdf90ff2a57eb72b235e Mon Sep 17 00:00:00 2001
From: Darren Loher <dloher@google.com>
Date: Tue, 12 Nov 2024 12:06:48 -0800
Subject: [PATCH] Add canonical OC to test README template (#3336)

* Update test-requirements-template.md to require Canonical OC section, written in JSON format
---
 doc/test-requirements-template.md | 87 ++++++++++++++++++++++++-------
 1 file changed, 68 insertions(+), 19 deletions(-)

diff --git a/doc/test-requirements-template.md b/doc/test-requirements-template.md
index 4a4abfb4830..4b65d1d866e 100644
--- a/doc/test-requirements-template.md
+++ b/doc/test-requirements-template.md
@@ -8,41 +8,89 @@ assignees: ''
 
 # Instructions for this template
 
-Below is the required template for writing test requirements.  Good examples of test
-requirements include:
+Below is the required template for writing test requirements.  Good examples of
+test requirements include:
 
-* [TE-3.7: Base Hierarchical NHG Update](/feature/gribi/otg_tests/base_hierarchical_nhg_update/README.md)
-* [gNMI-1.13: Telemetry: Optics Power and Bias Current](https://github.com/openconfig/featureprofiles/blob/main/feature/platform/tests/optics_power_and_bias_current_test/README.md)
-* [RT-5.1: Singleton Interface](https://github.com/openconfig/featureprofiles/blob/main/feature/interface/singleton/otg_tests/singleton_test/README.md)
+* [TE-18.1 gRIBI MPLS in UDP Encapsulation and
+  Decapsulation](https://github.com/openconfig/featureprofiles/blob/main/feature/gribi/otg_tests/mpls_in_udp/README.md)
+* [TE-3.7: Base Hierarchical NHG
+  Update](/feature/gribi/otg_tests/base_hierarchical_nhg_update/README.md)
+* [gNMI-1.13: Telemetry: Optics Power and Bias
+  Current](https://github.com/openconfig/featureprofiles/blob/main/feature/platform/tests/optics_power_and_bias_current_test/README.md)
 
 # TestID-x.y: Short name of test here
 
 ## Summary
 
-Write a few sentences or paragraphs describing the purpose and scope of the test.
+Write a few sentences or paragraphs describing the purpose and scope of the
+test.
 
 ## Testbed type
 
-* Specify the .testbed topology file from the [topologies](https://github.com/openconfig/featureprofiles/tree/main/topologies) folder to be used with this test
+* Specify the .testbed topology file from the
+  [topologies](https://github.com/openconfig/featureprofiles/tree/main/topologies)
+  folder to be used with this test
 
 ## Procedure
 
-* Test environment setup
-  * Description of procedure to configure ATE and DUT with pre-requisites making it possible to cover the intended paths and RPC's.
+### Test environment setup
+
+* Description of procedure to configure ATE and DUT with pre-requisites making
+  it possible to cover the intended paths and RPCs.
+
+### TestID-x.y.1 - Name of subtest 1
+
+The following steps are typically present in each subtest.
+
+* Step 1 - Generate DUT configuration
+
+Replace this JSON formatted content with the "Canonical OC" that is expected to
+be generated by the subtest. This configuration should be in JSON format.
+
+```json
+{
+  "openconfig-qos": {
+    "interfaces": [
+      {
+        "config": {
+          "interface-id": "PortChannel1.100"
+        },
+        "input": {
+          "classifiers": [
+            {
+              "classifier": "dest_A",
+              "config": {
+                "name": "dest_A",
+                "type": "IPV4"
+              }
+            }
+          ],
+          "scheduler-policy": {
+            "config": {
+              "name": "limit_group_A_1Gb"
+            }
+          }
+        },
+        "interface": "PortChannel1.100"
+      },
+    ]
+  }
+}
+```
+
+* Step 2 - Push configuration to DUT using gnmi.Set with REPLACE option
+* Step 3 - Send Traffic
+* Step 4 - Validation with pass/fail criteria
 
-* TestID-x.y.z - Name of subtest
-  * Step 1
-  * Step 2
-  * Validation and pass/fail criteria
+### TestID-x.y.2 - Name of subtest 2
 
-* TestID-x.y.z - Name of subtest
-  * Step 1
-  * Step 2
-  * Validation and pass/fail criteria
+Repeat the format of the first subtest for each additional subtest defined.
 
 ## OpenConfig Path and RPC Coverage
 
-This example yaml defines the OC paths intended to be covered by this test.  OC paths used for test environment setup are not required to be listed here.
+This yaml stanza defines the OC paths intended to be covered by this test.  OC
+paths used for test environment setup are not required to be listed here. This
+content is parsed by automation to derive the test coverage
 
 ```yaml
 paths:
@@ -64,6 +112,7 @@ rpcs:
 ## Required DUT platform
 
 * Specify the minimum DUT-type:
-  * MFF - A modular form factor device containing LINECARDs, FABRIC and redundant CONTROLLER_CARD components
+  * MFF - A modular form factor device containing LINECARDs, FABRIC and
+    redundant CONTROLLER_CARD components
   * FFF - fixed form factor
   * vRX - virtual router device