Scripts¶

Scripts

define the test sequence and operating modes of the test being run
are in human readable JSON file format
- JSON is used so that non-programmers may be able to read/edit 1 the script without requiring a programming background. This is useful in development or emergency situations.
extend JSON a little bit, by allowing comments, any line begining with # is a comment. This allows the script to be documented

The script has the following sections,

{
  "subs": {
  },
  "info": {
  },
  "config": {
  },
  "tests": [
  ]
}

subs¶

This is a section of User configurable substitutions for variables in the script. For example, if there was a test limit that could have two values, the values can be listed as a subs field and the user can select which one to use.

In a production environment, operators are not typically allowed to arbitrarily change values of test limits or any other setup. However, in an engineering lab, or new product ramp environment, having an easy method to change some parameters might be useful. This feature does not have to be used.

Only (logged in) users with a certain role privileges can access Test Config, and thus access to GUI controls that use the subs feature. Otherwise subs are used to create a Traveller, which stores the subs used.

subs are useful for generating Travellers.

Here is a full example of what subs section could look like (taken from example prod_1.scr),

"subs": {
  // Each item here is described by,
  // "<subs_name>":
  //   "title": "<title>",
  //   "type" : "<str|num>",
  //   "widget": "<textinput|select>",
  //   "regex": <"regex">,  // only for widget == textinput,
  //                           when regex is satisfied widget turns green
  //   "choices": [<choice1>, <choice2>, ...],  // only for widget == select
  //   "default": <default>,
  //   "subs": // inner dependant subs
  //           { <key1> : { "subs_name1": {"val": <>, "type": "<str|num>" }, ...},
  //             <key2> : { "subs_name1": {"val": <>, "type": "<str|num>" }, ...}
  //           }
  // }
  //
  // Rules:
  // 1. key must not have any spaces or special characters
  //
  "Lot": {
    "title": "Lot (format #####)",
    "type" : "str", "widget": "textinput", "regex": "^\\d{5}$", "default": "95035"
  },
  "Loc": {
    "title": "Location",
    "type" : "str", "widget": "select", "choices": ["canada/ontario/milton",
                                                    "us/newyork/buffalo"],
    // inner dependant substitutions based on user input
    "subs" : {"canada/ontario/milton": { "TST000Min": { "val": 0.1, "type": "num" }},
              "us/newyork/buffalo":    { "TST000Min": { "val": 0.2, "type": "num" }}
    }
  },
  "TST000Max": {
    "title": "TST000 Max Attenuation (db)",
    "type" : "num", "widget": "select", "choices": [9.0, 10.0, 11.0]
  },
  "TST000Enable": {
    "title": "TST000_Meas Enable",
    "type" : "str", "widget": "select", "choices": ["true", "false"]
  }

// and how it looks in the test item,
{"id": "TST000_Meas",     "enable": "%%TST000Enable", "args": {"min": "%%TST000Min", "max": "%%TST000Max"}},

key

the name of the variable to be replaced somewhere else in the script, for example, the variable could be in the info section
- the variable in other sections, would be named "%%key"
- the variable would be listed with double quotes, regardless of the variable type
key should not have any special characters in it, else bad things happen

title

this is the title of the field to be presented to the Operator in the Test Config view
if there is a specific format of the variable expected, that should be indicated in the title

type

indicates type of variable that is ultimately required in the final JSON version of the script
string (str) and number (num) (covers float and ints) are the only options

widget

the type of GUI widget to present to the Operator in the Test Config view
textinput is a generic text input box, which will be populated by the default field
select is a drop down selection menu

regex

used only for textinput widget
used to validate the Operator entered correct information
this is optional field

default

sets the default value for textinput widget
optional

Inner Subs¶

Inner subs allow one User sub to be able to set multiple other subs. An example is shown in the subs section above. In the above example, when Location is selected by the user, TST000Min is assigned a value depending on the Location selected.

info¶

This section is a list of fields that correspond to fields that exist in the backend database and are typically used for database searches.

You cannot add or delete fields from this section. If there are missing fields, an error will occur downstream as the result record is check to have these fields. New fields can be added, but that requires a request to customize the backend database. See TBD.

Note that the example here, two fields are using the subs section to get their values from the Operator in the Test Config view.

"info": {
  "product": "widget_1",
  "bom": "B00012-001",
  # list fields present user choice or fill in
  "lot": "%%Lot",
  "location": "%%Loc",
  // "config": "optional"
},

product - 32 character length field.

bom - 32 character length field. Note bom stands for Bill of Materials.

lot - 16 character length field.

location - 128 character length field.

config - (optional) 16 character length field.

Defining rules and a naming convention for these fields will help you later when you need to make database searches for specific sets of results. This is important.

config¶

This section sets required variables that Prism uses to drive the test script.

"config": {
  "fail_fast": true,
  "drivers": ["public.prism.drivers.fake.fake"]
},

fail_fast

this directive tells Prism whether to stop the test script on the first occurrence of a failed test
this directive can be overridden by the directive in the options section of the tests section - in other words, here it has the least priority
it is recommended fail_fast be set to true.
- Often tests are interdependent, and if one test fails, it often means other tests will fail that depended on that particular function. What happens then is a cascade of failed tests which my might obscure the root failure.
- If tests are mutually exclusive, it may be advantages to set fail_fast to false.

drivers

this is a list of drivers to start when the script it loaded
the dot notation is specifying a directory path to the python file to read
every script must have a driver. A fake driver is available in the case where you don’t want/need a real driver, for example, in development of code
See Drivers

tests¶

This section has a list of test definitions

each definition has fields module, options, items
items has fields id, enable, fail, and args

Consider the following test section, which only has ONE test definition in the JSON list. An example of more than one test definition will be shown later.

See public/prism/scripts/example/prod_v0/tst00xx.py for usage.

"tests": [
  {
    "module": "public.prism.scripts.prod_v0.tst00xx",
    "options": {
      "fail_fast": false
      # add more key/value as required
    },
    "items": [
      {"id": "TST0xxSETUP",           "enable": true },
      {"id": "TST000_Meas",           "enable": true, "args": {"min": 0, "max": "%%TST000Max"},
                                      "fail": [ {"fid": "TST000-0", "msg": "Component apple R1"},
                                                {"fid": "TST000-1", "msg": "Component banana R1"}] },
      {"id": "TST001_Skip",           "enable": false },
      {"id": "TST0xxTRDN",            "enable": true }
    ]
  }
]

module

a dot notation path to the Python code that is associated with this test definition

options

a list of fields assigned values that persist over the execution life of the test item definition
Prism key words,
- fail_fast overrides fail_fast in the config section
- enable (defaults to true) when set to false, disables all tests in items
add fields here as your application requires
these options fields are available programmatically to each test items
- for example, you could have a global value assigned here that any test items can access

items

a list of test items
the system will execute these tests in order
- id - A unique identifier of the test, which is also the Python (class) function name in module.
- enable - true or false, can be omitted if always enabled
- args - a list of key/value pairs of any name/value required by your application
  - in the example shown, min and max keys are used and assigned values
  - note that max is using a subs entry
- fail - a list of failure messages to present to the Operator and to store in the result database
  - These failure modes are accessed programmatically by your test code, see TBD
  - fid - a unique ID for this failure mode
  - msg - message to show operator

1: Scripts CAN BE LOCKED DOWN so that a production user cannot change them. Locking down the Prism is covered TBD.