Introduction
The Xerox IPP Server Test Tool enables implementers of the Internet Printing Protocol (IPP) to test their implementations. The tool automates the process of submitting an arbitrary number of operation requests to an IPP server (Printer object), collecting responses, and comparing the responses to expected results. When invoked, the IPP Server Test Tool sends specified IPP operations over the wire to the target IPP server (printer). The IPP Server Test Tool was designed to run with JDK 1.6 and was tested on Windows NT 4.0, Windows 95, and Solaris 2.0.
The IPP Server Test Tool supports all IPP syntaxes except octetString as specified in the Internet Printing Protocol 1.0: Model and Semantics (draft-ietf-ipp-model-10.txt, June 30, 1998 ) published by the Internet Engineering Task Force (IETF).
The flexibility of the IPP Server Test Tool driver program and the language will make the combination more than a pass/fail conformance tester, making it a useful development/debugging tool.
The IPP Server Test Tool as delivered includes of the following plain-text files:
|
IppTest.bat |
The driver program that invokes the IPP Server Test Tool. |
|
StdDefs.test |
A script file containing IPP standard definitions for attributes, attribute groups, and operation requests. |
|
MyPrinterDefs.test |
A script file containing definitions specific to the target IPP Printer object being tested. Before running the IPP Server Test Tool, edit this file to include the name/URI of your target printer. Rename the file to reflect the target printer, if desired (e.g., N32Defs.test). Customize the file to suit your implementation by defining extension attributes and operation requests. Edit it also to include bogus attributes, groups, syntaxes, and operation requests to test the effect on your printer. |
|
Basic.test |
The primary input file containing operation requests and expected responses used to exercise the target IPP Printer object. |
IPP Server Test Tool invocation
The command to invoke the IPP Server Test Tool is:
Where switches indicates 0 or more occurrences of the following:
-report {list of report-names} |
A report-name is one of the words listed in the below. A list of report-names is a comma-separated list. |
all |
Show everything. |
annotations |
Show annotations (input file lines beginning with @). |
debug |
Show debugging information. This includes a program trace, as well as lower-level details of requests and responses as they are sent and received. |
expected |
Show expected responses as they are read. |
mismatches |
Show mismatches between expected and actual responses. |
requests |
Show requests as they are being sent. |
responses |
Show responses as they are received. |
summary |
Show mismatches and annotations (the default). |
verbose |
Show everything except debugging information. |
Test file names are the script files that you want to use for the test. The set of test files delivered with the IPP Server Test Tool are:
StdDefs.test
MyPrinterDefs.test
Basic.test
All switches and file names are optional. There can be any number of either, and they can occur in any order. Of course, to do anything useful, you must specify at least one script file with at least one request and supporting definitions.
The effect of switches applies to all files that follow them on the command line. In the following command line, the switches apply to all three of the files:
IppTest.bat {switches} StdDefs.test MyPrinterDefs.test Basic.test
Examples:
IppTest.bat MyFile.test |
Run MyFile.test with the default output (annotations and mismatches). |
IppTest.bat -report summary MyFile.test |
Equivalent to the above. |
IppTest.bat -report annotations,mismatches MyFile.test |
Equivalent to the above. |
Often, it is desirable to apply switches to only certain files. For example, "-report debug" generates a lot of output, so you probably do not want to apply it to all files:
IppTest.bat StdDefs.test MyPrinterDefs.test -report debug Basic.test
Test file contents
As indicated above, the IPP Server Test Tool uses one or more files that specify the information required to run the test tool. The information consists of:
|
Attribute, attribute group, and operation definitions |
Definitions of the standard set of IPP attributes, attribute groups, and operation requests, any implementation-specific extensions, and any bogus information to further test the target printer. |
|
Symbol definitions |
Definitions of symbols to avoid hard-wiring changeable values, and that are specific to the printer under test. |
|
Request/expected response input |
One or more operation requests followed by zero or more expected responses. You may specify any number of requests/expected responses. |
Though all definitions and request/expected response sets may be included in the same file, the recommendation is to use multiple files. Definitions placed in a file separate from the request invocations and expected responses allows for sets of standard definitions to be placed in shared files. It is possible, however, to define (or redefine or undefine) attributes, attribute groups, and/or requests at any point in a request/expected response input file.
A description of each definition type and of requests and expected responses follows.
Definitions
Definitions may be placed in one or more script files. As mentioned above, the recommendation is to use multiple files. With regard to definitions, the recommendation is to maintain a standard set of definitions based on the IPP specification (as in the StdDefs.test file), and one or more symbol definitions files that contain definitions specific to the printer under test.
IPP attribute definitions
Defining an attribute means specifying an attribute's name and syntax. The driver program recognizes the legal IPP syntax names (except octetString), but has no pre-conceived notion of what attributes should exist. Example:
Define Attribute printer-uri uri
In the example, printer-uri is the attribute name, uri is the attribute syntax.
The attribute names and attribute syntaxes included in the StdDefs.test file have names that are compatible with those defined in the Internet Printing Protocol 1.0: Model and Semantics. The IPP Server Test Tool does not check the attribute names. However, the attribute syntaxes are hard-wired and are faithful to the terminology used in the IPP specification. For example, the IPP Server Test Tool handles simple syntaxes such as integer and boolean as expected. The following examples indicate how the IPP Server Test Tool expects specifications for integer and boolean syntax attributes:
copies: 5
color-supported: false
For other syntaxes, the IPP Server Test Tool recognizes certain forms for values that correspond to the IPP specification. Example:
Define Attribute printer-state enum \
idle(3), \
processing, \
stopped
The example indicates that the enum value sequence begins with 3. Enum values may be skipped by specifying the parenthetical enum. Specifying processing (5), in the example above would indicate skipping enum value 4. Note the use of commas in specifying enum values.
Also note the use of 1setOf:
Define Attribute page-ranges 1setOf rangeOfInteger
For additional examples of syntax specifications refer to the StdDefs.test file.
IPP attribute group definitions
Defining a group means associating a name with a byte-value. The standard values are those specified in the Internet Printing Protocol 1.0: Encoding and Transport (draft-ietf-ipp-protocol-06.txt, June 30, 1998) published by the Internet Engineering Task Force (IETF). Example:
Define Group Operation 0x01
Symbol definitions
Definitions of symbols to avoid hard-wiring changeable values. For example, the Basic.test file refers to "$target", which assumes that the symbol "target" has been defined as the URI of the printer under test. Example:
Define Symbol target 'Your-printer-URI'
IPP request definitions
The IPP Server Test Tool driver program does not have a fixed set of recognized operations. Defining a request means associating a name with an operation code (op-code). The Internet Printing Protocol 1.0: Model and Semantics specifies the standard operation codes, including those for implementation extensions. Example:
Define Request Print-Job 0x0002
Requests and expected responses
The IPP Server Test Tool driver program checks each expected response against the actual response from the preceding request. If there is no expected response following a request, the test tool continues through subsequent requests in the script.
The driver program normally runs along silently until it encounters a mismatch between expected and actual results. It is possible, however, to generate various forms of output, logging any combination of requests sent, responses received, responses expected, and user-supplied notes using annotations in the test files (see the description of switches under IPP Server Test Tool Invocation). By default, all test tool output is written to stdout.
Note that all definable entities (attributes, attribute groups, requests, and symbols) must be defined (e.g., by StdDefs.test and MyPrinterDefs.test files) before they are used in a request or expected response.
Operation requests
The script file supplies the operation request name along with any combination of attributes and optional document data. The driver checks to make sure that the request name has an op-code assigned to it, that the attributes have been previously defined, and that the supplied attribute values are consistent with their defined syntaxes. Example operation request in the input file:
Print-Job \
target: $target, \
attributes: ( \
Operation: ( \
attributes-charset: utf-8, \
attributes-natural-language: en-us, \
requesting-user-name: 'Joe Tester', \
job-name: 'Good Job', \
document-name: 'Sample', \
document-format: 'application/postscript' \
) \
), \
data: TheFileToPrint.ps \
Note that $target should already have been defined (as in the recommended MyPrinterDefs.test file), and that the Print-Job operation and all listed attributes should already have been defined (standard definitions are supplied by the StdDefs.test file).
Expected responses
Expected responses are also specified using the previously-defined attributes and groups. The driver program makes the same kinds of syntax checks as it does for requests. Example specification of an expected response in the input file:
Expect Response \
status-code: 0, \
attributes: ( \
Operation: ( \
attributes-charset: utf-8, \
attributes-natural-language: en-us, \
... \
), \
Job: ( \
job-uri: *, \
goodJobId = job-id: *, \
job-state: *, \
... \
) \
)
Note that status-code, the Operation and Job attribute groups, and the listed attributes should already have been defined.
Note also that a new symbol, goodJobID, is created to capture the job-id returned by the response to the Print-Job request example given above.
The specified values may be expressions involving logical operators and nested sub-expressions. The driver program attempts to match the actual attribute values to the specified expressions. The matching process is order-independent, per the Internet Printing Protocol 1.0: Model and Semantics specification. Depending on how an expression is written, it is possible to require an exact match, or to allow a value to be within a given range ( : operator), or to satisfy one of a set of alternatives ( | operator).
Special syntax allows the expected response to require the presence of an attribute, without specifying its value. Example:
job-id: *
It is also possible to specify that a response group may contain additional values, without specifying what they are. Example (part of an expected response):
Operation: ( \
attributes-charset: utf-8, \
attributes-natural-language: en-us, \
... \
The ellipsis indicates that any other operation attribute included in the actual response is okay. (The attributes attributes-charset and attributes-natural-language, however, are required in the actual response.)
The IPP Server Test Tool uses the C language concept of casting to specify that only a certain syntax type value is acceptable for multiple syntax attributes. This is useful when an attribute has multiple syntaxes, and you want to be explicit about which syntax applies. This feature is not implemented in Version 1.0.
EXAMPLE
For a multi-syntax attribute, an OR operator ( | ) is placed between the alternative syntaxes. Example:
Define Attribute job-sheets keyword|nameWithoutLanguage|nameWithLanguage
Test file conventions
Note the following use conventions for the IPP Server Test Tool files:
|
# |
Lines beginning with a pound sign are comments. |
|
|
@ |
Lines beginning with the @ sign are annotations. Annotations are similar to comments, except that the driver program copies them to the output. The use of annotations enables you to track the progress of the test. |
|
|
(end-of-line) |
An end-of-line (physical line) terminates a command. |
|
|
\ |
A backslash may be used at the end of the current physical line to continue the logical line with the next physical line. |
|
|
' ' |
Values containing other than alpha, digit, and hyphen characters must be enclosed in single quotes ( ' ). In particular, URIs must be enclosed in single quotes. |
|
|
| |
The vertical bar indicates the Or operator in expected responses. Example: en | en-us |
|
|
& |
The ampersand indicates the And operator in expected responses. |
|
|
! |
The exclamation point indicates the Not operator in expected responses. |
|
|
: |
The colon indicates the range operator. The range operator may be used with enum and integer values. Example: orientation-requested: landscape:reverse-landscape (The attribute orientation-requested is an enum syntax attribute.) |
|
|
* |
The wildcard character indicates that any value for an attribute is acceptable. |
Error checking
The IPP Server Test Tool checks for two primary types of errors:
|
Syntax errors |
The IPP Server Test Tool checks for improper use of "Define" statements, "Symbol" statements, etc. The IPP Server Test Tool checks for consistency between the syntax of an attribute and the length of the attribute value. In particular, this applies to values received from the server. NOTE: Length checking is not implemented in Version 1.0. |
|
Actual response varies from expected response |
The IPP Server Test Tool returns a message if an actual response does not match the specified expected response. The test tool continues to run. To be implemented: User-settable default indicating the number of response mismatches allowed before the test tool stops operation. |
The IPP Server Test Tool indicates the line number and offset of the script file where it encounters a problem.