Skip to content

YAML Syntax

Jump to bottom Edit New page
Alden Hart edited this page May 24, 2015 · 40 revisions

This page describes the YAML syntax used by the tester. This page documents conventions that are used across the various JavaScript files that make up the test framework.

Recognize that different tests may use, extend, or ignore the syntax described here - in any way that's useful for that test. Please refer to the individual readme.md files in the /spec/... subdirectory for the definitive syntax for a given test suite. Most should refer back to here, though.

Test Suites and Directory Structure

(#### Rob: Please confirm. I'm inferring here... Are there naming conventions?)

The root directory for tests is /spec. There can be one test suite in each leaf directory, consisting of a JavaScript file (ex: 001-arcs-spec.js) and a parent YAML file (ex: 001-arcTests.yml). The root JavaScript object for that test is test.

Globals and Substitution

In the top-level of each test suite will be a variables key that should be a hash of strings or hashes, and hashes can be nested to arbitrary depth. (Arrays are not currently supported.)

You can then refer to the contents of one of those globals using the $token or ${token} syntax. The token string will be split on . and used as the path into the variables hash. The result must be a number or a string.

For example, if the yaml contains:

variables:
  timeout: 10
  stat:
    stop: 3

test:
  # Other stuff...
  endCondition: { stat: $stat.stop }
  timeout: ${timeout}

The resulting javascript value for test.timeout will be 10, since it looked in the variables hash for timeout, and got a return value of 10.

Similarly, the resulting javascript value for test.endCondition.stat will be 3, since it looked in the variables hash for stat, then inside that for stop, and got a return value of 3.

Including other files

If any object contains the key include followed by a file name it will load the contents of the file referred to and overwrite the contents of the parent object with the contents of the file. Other keys that are not in the file, but are in the object, will remain in the resulting object. (IOW, the file and the object with the include are merged and implement inheritance).

As a special exception, if the top level of the referred-to file is an array, then the object will be replaced with the array from the file. There will not be a merge of the file contents and the included file. Further, if the container of the object with the include is an array, and the contents of the referred-to file is an array, then the the array contents will be spliced into the parent array in place of the object.

(#### Some examples of how this is useful and used would be nice. You obviously put this in here for a reason.)

Nested tests

If a test contains the key test that is an array of objects, then it will be treated as a "suite". (##### says test here, but tests in the .yml file)

The top-level suite has two special keys:

  • precondition

    • This is where the top-level beforeEach, beforeAll, timeout, etc keys that apply to all suites are found. This is different from other suites where these keys are found in the suite data itself. Otherwise all values are interpreted in the same manner.

  • variables

    • this is the dictionary that will be used for all variable substitutions throughout the file and all included files. This happens when the data is loaded.

Suites can have the following tags:

  • beforeAll, beforeEach

    • These are strings (possibly multi-line) that contains gcode that will be executed before all tests or before each test (respectively).
    • beforeAll will be considered "done" when there have been as many {r: ...} responses as lines in the beforeAll string. This will ignore the response code (in the footer) and status reports!
    • beforeEach will be considered "done" when an {sr: {stat: 3}} is received.
    • TODO - Provide an endCondition mechanism the beforeAll and beforeEach.

  • setValues, setValuesEach

    • These arrays represent data to be converted to JSON and sent to the TinyG before all tests or before each test, respectively.

    • After each value is sent it will wait for one {r: ... } response. There will be no attempt to ensure that the response and the sent data match. The response code in the footer will be ignored.

    • For example, to configure the status reports, you can use:

      #...
setValues:
  - sr:
    posx: true
    posy: true
    stat: true

    • Care must be taken to always have at least stat in the status reports, and to not turn status reports off completely. If status reports are turned off, the rc key may be used in endCondition to terminate tests. Use with caution.

  • timeout

    • This is the same as the timeout value of the contained tests, and will be used as the default for all nested tests. Timeout is in seconds, and may have a fractional part.

  • endCondition

    • This hash provides key->value pairs to match the rolling status reports (sr). Any key provided that matches that same key of any status report will consider each contained test as "done". Examples:

      endCondition: { stat: 3 }
endCondition: { stat: $stat.stop }

    • rc may also be used as an endCondition. This refers to the response code (status code) in the second position of the footer of a {r: ...} response. This will end the test on the first response that matches. Examples:

      endCondition: { rc: 0 }
endCondition: { rc: $rc.OK }

    • If no endCondition is specified, the endCondition of the parent suite (or parent of the parent, etc) will be used. If the parent suite didn't specify an endCondition then the default value will be used:

    • Each test can override (but not add to) the specified endCondition.

    • All other endCondition (and endState) keys are compared against the same keys of a rolling recording of all {sr: {...}} status reports. (#### I'm not sure what this means or if my editing has destroyed the proper meaning)

    • All provided endCondition (and endState) keys must match values with the status report (or response code), or the test will fail.

  • endState

    • This hash is compared against the rolling status reports once the endCondition has matched. If the state is matched the test passes. If it is not matched the test fails.
    • For example endState: { posx: 20.5, posy: 1.25, posz: -4.000 } can be used to test for that end position
    • The rc key can also be used as an endState to match a specific response code. A value of 0 is STAT_OK.
    • Values of the endCondition are not used for endState, so if you need a value to be both an endCondition and matched in the endState, you must specify it in both.

  • manualPrompt

    • This will add a manual prompt after a test.
    • The text string provided as the manualPrompt value will be displayed, followed by (y/n/q). The user can then type y to pass the test, n to fail it, or q to fail it and quit all further testing (Note: finalization is still performed #### verify).
    • If the value true is passed, then the name of this test will be used as the prompt.
    • The manual test will be run regardless of whether the automatic test passed or not.

  • focus

    • If true, then only this test (and all other tests that have focus: true) will be executed.
    • If focus is declared in the before section of a test suite than that entire suite will be in focus.
    • If no tests in the system have focus set to true, then all tests are run.
    • The value false can be used, or the focus key can be absent. Both yield the same results.
    • This is useful for turning groups of tests on and off using substitutions.

Tests

Each test can contain the following keys:

  • name - This is the name of the test to be reported if the test fails.

  • gcode - This is the code the send to the TinyG for this test. It may be made into multiple lines using the | operator:

    # Inside the test:
- name: Example Test
  gcode: |
    ; This is interpreted as gcode (this line is read as a Gcode comment)
    g0 x0 y0 ; go to x0 y0
    ; Care must be taken to indent all the gcode lines at the same or 
    ; deeper level in order for the yaml parser to keep them in one block.

  • endCondition - see above

  • endState - see above

  • manualPrompt - see above

  • focus - see above

YAML Pointers

This section is not an attempt to explain YAML (See here (#### insert a good reference), but does highlight some things that are useful when creating and editing tests.

  • Unlike JSON, YAML requires a space after the : Forgetting this space will cause the test file to fail.
  • YAML uses # for comments, and does not support block comments. TinyG supports (, ;, and % for comments. So comment lines with # are for YAML lines and those others are for lines that are passed to the unit under test. This leads to text that look like this:
  gcodeDefaults: |    # initial values for gcode state
    G21 G94 G90 G91.1	; set initial Gcode state
    G10 L2 P1 X0 Y0 Z0	; clear G54 offsets
    G10 L2 P2 X0 Y0 Z0	; clear G55 offsets
    G10 L2 P3 X0 Y0 Z0	; clear G56 offsets
    G10 L2 P4 X0 Y0 Z0	; clear G57 offsets
    G10 L2 P5 X0 Y0 Z0	; clear G58 offsets
    G10 L2 P6 X0 Y0 Z0	; clear G59 offsets
    G54	; select G54 coordinates

References

Add a custom footer
Add a custom sidebar
Clone this wiki locally