# IppServerTestAddednum.txt # Last revised by Xerox Corporation on 99-02-25. # Copyright (c) 1998, 1999 by Xerox Corporation. All rights reserved. # Addendum to IppServerTestUserGuide.htm version 1.0 # Describes enhancements for IPP Server Test Tool, v 1.2 (PWG IPP BakeOff #2) Section A1 - Capturing Response Values in Symbols ------------------------------------------------- Capturing response values in symbols is now implemented. For example, from the script BO21-22.test: Expect Response \ status-code: 0, \ attributes: ( \ Operation: ( \ oa08 = attributes-charset: utf-8, \ oa09 = attributes-natural-language: *, \ ... \ ), \ In the above example, the symbols "oa08" and "oa09" will be set to the values of "attributes-charset" and "attributes-natural-language". The symbols can be used (dereferenced) like other symbols; eg, Echo oa08 = attributes-charset = $oa08 Echo oa09 = attributes-natural-language = $oa09 Section A2 - "Echo" Command ------------------------------------------------- The Echo command is similar to the "@" annotation character. It's arguments are output to the standard out, with symbol expansions; eg, Echo oa08 = attributes-charset = $oa08 Echo oa09 = attributes-natural-language = $oa09 might appear in the output as: oa08 = attributes-charset = utf-8 oa09 = attributes-natural-language = en-us Section A3 - "Include" Command ------------------------------------------------- The Include command is similar to the "#include" directive used in C-language programs. It takes a single argument, which must be the name of a test input file. When an Include command is encountered, processing of the current file is suspended; the included file is processed to completion; and processing of the current file resumes at the next command following the Include. Symbol definitions are propogated to and from Include'd files, providing a primitive means to "pass arguments": # minCharset.test references $gOperation as an "argument" # specifying the IPP operation request to send. Define Symbol gOperation Validate-Job Include minCharset.test Section A4 - Unordered Comparison of 1setOf X Values ------------------------------------------------- Comparisons of actual vs expected values for "1setOf X" attributes is now independent of the order of the sub-values. In addition, an elipsis may be used at the end of the list of sub-values to indicate that additional values may be present. Consider the following expected value specification: operations-supported: < \ print-job, \ validate-job, \ cancel-job, \ get-job-attributes, \ get-jobs, \ get-printer-attributes, \ ... \ > The above example says that the "operations-supported" attribute must contain each of the operations (sub-values) listed, but *may* contain other operations as well. The order of the sub-values is unimportant. Section A5 - "If" Command ------------------------------------------------- An If/Else/EndIf construct allows conditional execution of commands, dependent on the value of a Symbol. If the symbol holds the value of an attribute (as captured from an expected response - see Section A1), the comparison value can use the same logical syntax as used for expected values of that attribute; eg, assuming that the symbol "ops-supported" contains the value of the "operations-supported" attribute, the following If/Else can be constructed: If [$ops-supported: ] Echo Pause-Printer and Resume-Printer are implemented Else If [$ops-supported: | ] Echo Error: If either Pause-Printer or Resume-Printer \ are implemented, both of them must be. EndIf EndIf In the above example, the OR operator ("|") can be used because the symbol "ops-supported" contains the value of an attribute. The sub-value lists enclosed in angle brackets are used because the attribute ("operations-supported") is a "1setOf X". "If", "Else", and "EndIf" must appear as the first tokens on a line. Any legal command may appear in-between, including IPP requests and expected responses. The "Else" part is optional. If the symbol does not contain the value of an attribute (i.e., if it was "set" via "Define Symbol"), then a simple string comparison (case- and whitespace- sensitive) will be made between the value of the symbol and the collection of tokens between the colon (":") and the right square-bracket. Section A6 - "IfDef" and "IfNDef" Commands ------------------------------------------------- The IfDef/Else/EndIf and IfNDef/Else/EndIf constructs allow conditional execution of commands, dependent on the "existance" of a Symbol. In this case, "existance" indicates whether the symbol is defined or not. Example: IfDef mySym Echo The symbol mySym is defined, and its value is $mySym. Else Echo The symbol mySym is undefined. EndIf In the above example, the commands between the "IfDef" line and the "Else" line are executed if the symbol mySym has been defined; otherwise, the commands between the "Else" line and the "EndIf" line are executed. "IfNDef" works similarly, though the test is for the opposite condition. Section A7 - Testing the Outcome of a Previous Command ------------------------------------------------- The special symbol "%status" (note the leading percent-sign) indicates the completion status of the previous command. Currently, "%status" is implemented only for expected response comparisons, and can have one of the following values: "ok", "failure", and "error". Note that "%status" is *not* the same as the status-code returned in an IPP response. Here's an example of using "%status" in an "If" construct: If [$%status: ok] Echo Previous expected response matched actual response. EndIf Note that all command reset the value of status; in this case, commands include things like "#" (beginning of a comment), "@", or an "If". Thus, it is often useful to save the value of "%status" in another symbol until it can be used; e.g., # Current value of %status is lost immediately following Definition Define Symbol saved-status $%status # Check the saved-status If [$saved-status: ok] Echo Previous expected response matched actual response. Else If [$saved-status: failure] Echo Previous expected response did not match actual response Else Echo Previous expected response had an unexpected problem \ e.g., a syntax error or server not responding. EndIf EndIf Section A8 - "Casting" an Attribute Value with Ambiguous Syntax ------------------------------------------------- Some attributes are defined to have alternative syntaxes; in most such cases, the Server Test Tool can determine the intended syntax by appearance alone. For example, "job-name" is defined as: Define Attribute job-name nameWithoutLanguage | nameWithLanguage In a request, the syntax for a "job-name" value can be easily deduced: # This is a "nameWithoutLanguage" value job-name: 'My Job' # This is a "nameWithLanguage" value job-name: Other attributes are more problematic; consider the definition of "media": Define Attribute media keyword | \ nameWithoutLanguage | nameWithLanguage # This is a "nameWithLanguage" value media: # This is ambiguous: could be a "keyword" or a "nameWithoutLanguage" media: iso-a4-white To disambiguate the syntax, a construct similar to a C-language "cast" is used. A cast is indicated by an IPP syntax name, surrounded by parentheses, immediately preceeding a value: # This is a "keyword" value media: (keyword)iso-a4-white # This is a "nameWithoutLanguage" value media: (nameWithoutLanguage)iso-a4-white Note that for *expected values*, ambiguous value specifications imply the *union* of the possible interpretations; thus, # In an expected response, the following indicates that the actual # value for "media" may be a "nameWithLanguage", # a "nameWithoutLanguage", or a "keyword": media: | iso-a4-white Section A9 - Status Codes: Value Names, Expressions and Symbols ------------------------------------------------- New support for status codes allows a script to manipulate their values in a fashion more consistent with other values returned from an IPP response. In particular, status codes are now treated like "enum" values, with associated names. The names are taken from the IPP Model specification - see StdDefs.test for precise details. When specifying an expected status code value, one can use either the numeric (decimal or hex) value, or the name. Futhermore, expressions may be used, as with other "enum" values. Examples: # Require status-code to be "successful-ok" Expect Response \ status-code: successful-ok, \ # Require status-code to be one of the "ok" values Expect Response \ status-code: successful-ok:successful-ok-conflicting-attributes, \ Additionally, status code values may be assigned to symbols for later use, as with other expected values; e.g., # Require status-code to be "successful-ok" Expect Response \ saved-status-code = status-code: *, \ # Do something based on status-code of some earlier IPP response If [$saved-status-code: !successful-ok] Echo Earlier request failed, so we'll try something different ... EndIf Section A10 - Out-of-Band Values ------------------------------------------------- All defined attributes are now capable of taking on any of the 3 out-of-band-values described in the IPP Model specification. To specify one of these values in an expected response, use one of the reserved words "unsupported", "unknown", or "no-value"; for example: Expect Response \ status-code: *, \ attributes: ( \ Unsupported: ( \ media: unsupported, \ ), \ Note that the special wildcard value, "*", matches all legal values for the specified attribute, including the out-of-band values.