]>
Commit | Line | Data |
---|---|---|
f8b3a85b MS |
1 | .\" |
2 | .\" "$Id$" | |
3 | .\" | |
4 | .\" ipp.test man page for CUPS. | |
5 | .\" | |
6 | .\" Copyright 2010 by Apple Inc. | |
7 | .\" | |
8 | .\" These coded instructions, statements, and computer programs are the | |
9 | .\" property of Apple Inc. and are protected by Federal copyright | |
10 | .\" law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
11 | .\" which should have been included with this file. If this file is | |
12 | .\" file is missing or damaged, see the license at "http://www.cups.org/". | |
13 | .\" | |
14 | .TH ipp.test 5 "CUPS" "23 February 2010" "Apple Inc." | |
15 | .SH NAME | |
16 | ipp.test \- ipptest test file format | |
17 | ||
18 | .SH DESCRIPTION | |
19 | The \fIipptest(1)\fR program accepts free-form plain text files that describe | |
20 | one or more IPP operation tests. Comments start with the "#" character and | |
21 | continue to the end of the line. Each test is enclosed by curley braces, for | |
22 | example: | |
23 | .nf | |
24 | ||
25 | # This is a comment | |
26 | { | |
27 | # The name of the test | |
28 | NAME "Print PostScript Job" | |
29 | ||
30 | # The request to send | |
31 | OPERATION Print-Job | |
32 | GROUP operation | |
33 | ATTR charset attributes-charset utf-8 | |
34 | ATTR language attributes-natural-language en | |
35 | ATTR uri printer-uri $uri | |
36 | ATTR name requesting-user-name $user | |
37 | FILE testfile.ps | |
38 | ||
39 | # The response to expect | |
40 | STATUS successful-ok | |
41 | EXPECT attributes-charset OF-TYPE charset | |
42 | EXPECT attributes-natural-language OF-TYPE naturalLanguage | |
43 | EXPECT job-id OF-TYPE integer | |
44 | EXPECT job-uri OF-TYPE uri | |
45 | } | |
46 | { | |
47 | # The name of the test | |
48 | NAME "Get Attributes of PostScript Job" | |
49 | ||
50 | # The request to send | |
51 | OPERATION Get-Job-Attributes | |
52 | GROUP operation | |
53 | ATTR charset attributes-charset utf-8 | |
54 | ATTR language attributes-natural-language en | |
55 | ATTR uri printer-uri $uri | |
56 | ATTR integer job-id $job-id | |
57 | ATTR name requesting-user-name $user | |
58 | ||
59 | # The response to expect | |
60 | STATUS successful-ok | |
61 | EXPECT attributes-charset OF-TYPE charset | |
62 | EXPECT attributes-natural-language OF-TYPE naturalLanguage | |
63 | EXPECT job-id OF-TYPE integer | |
64 | EXPECT job-uri OF-TYPE uri | |
65 | EXPECT job-state OF-TYPE enum | |
66 | EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user" | |
67 | } | |
68 | .fi | |
69 | ||
70 | .SH TOP-LEVEL DIRECTIVES | |
71 | The following directives can be used outside of a test: | |
72 | .TP 5 | |
73 | { test } | |
74 | Defines a test. | |
75 | .TP 5 | |
76 | DEFINE variable-name value | |
77 | Defines the named variable to the given value. This is equivalent to specifying | |
78 | "-d variable-name=value" on the \fIipptest\fR command-line. | |
79 | .TP 5 | |
80 | INCLUDE "filename" | |
81 | .TP 5 | |
82 | INCLUDE <filename> | |
83 | Includes another test file. The first form includes a file relative to the | |
84 | current test file, while the second form includes a file from the \fIipptest\fR | |
85 | include directory. | |
86 | .TP 5 | |
87 | TRANSFER auto | |
88 | Specifies that tests will, by default, use "Transfer-Encoding: chunked" for | |
89 | requests with attached files and "Content-Length:" for requests without attached | |
90 | files. | |
91 | .TP 5 | |
92 | TRANSFER chunked | |
93 | Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding: | |
94 | chunked" header. This is the default and is equivalent to specifying "-c" on the | |
95 | \fIipptest\fR command-line. Support for chunked requests is required for | |
96 | conformance with all versions of IPP. | |
97 | .TP 5 | |
98 | TRANSFER length | |
99 | Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:" | |
100 | header. This is equivalent to specifying "-l" on the \fIipptest\fR command-line. | |
101 | Support for content length requests is required for conformance with all | |
102 | versions of IPP. | |
103 | .TP 5 | |
104 | VERSION 1.0 | |
105 | .TP 5 | |
106 | VERSION 1.1 | |
107 | .TP 5 | |
108 | VERSION 2.0 | |
109 | .TP 5 | |
110 | VERSION 2.1 | |
111 | .TP 5 | |
112 | VERSION 2.2 | |
113 | Specifies the default IPP version number to use for the tests that follow. | |
114 | ||
115 | .SH TEST DIRECTIVES | |
116 | The following directives are understood in a test: | |
117 | .TP 5 | |
118 | ATTR tag attribute-name value(s) | |
119 | Adds an attribute to the test request. Values are separated by the comma (",") | |
120 | character - escape commas using the "\" character. | |
121 | .TP 5 | |
122 | ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... { ... } ] | |
123 | Adds a collection attribute to the test request. Member attributes follow the | |
124 | same syntax as regular attributes and can themselves be nested collections. | |
125 | Multiple collection values can be supplied as needed. | |
126 | .TP 5 | |
127 | DELAY seconds | |
128 | Specifies a delay before this test will be run. | |
129 | .TP 5 | |
130 | DISPLAY attribute-name | |
131 | Specifies that value of the named attribute should be output as part of the | |
132 | test report. | |
133 | .TP 5 | |
134 | EXPECT attribute-name [ predicate(s) ] | |
135 | .TP 5 | |
136 | EXPECT ?attribute-name predicate(s) | |
137 | .TP 5 | |
138 | EXPECT !attribute-name | |
139 | Specifies that the response must/may/must not include the named attribute. | |
140 | Additional requirements can be added as predicates - see the "EXPECT PREDICATES" | |
141 | section for more information on predicates. | |
142 | .TP 5 | |
143 | FILE filename | |
144 | Specifies a file to include at the end of the request. This is typically used | |
145 | when sending a test print file. | |
146 | .TP 5 | |
147 | GROUP tag | |
148 | Specifies the group tag for subsequent attributes in the request. | |
149 | .TP 5 | |
150 | NAME "literal string" | |
151 | Specifies the human-readable name of the test. | |
152 | .TP 5 | |
153 | OPERATION operation-code | |
154 | Specifies the operation to be performed. | |
155 | .TP 5 | |
156 | REQUEST-ID number | |
157 | .TP 5 | |
158 | REQUEST-ID random | |
159 | Specifies the request-id value to use in the request, either an integer or the | |
160 | word "random" to use a randomly generated value (the default). | |
161 | .TP 5 | |
162 | RESOURCE path | |
163 | Specifies an alternate resource path that is used for the HTTP POST request. | |
164 | The default is the resource from the URI provided to the \fIipptest\fR program. | |
165 | .TP 5 | |
166 | STATUS status-code [ predicate ] | |
167 | Specifies an expected response status-code value. Additional requirements can be | |
168 | added as predicates - see the "STATUS PREDICATES" section for more information | |
169 | on predicates. | |
170 | .TP 5 | |
171 | TRANSFER auto | |
172 | Specifies that this test will use "Transfer-Encoding: chunked" if it has an | |
173 | attached file or "Content-Length:" otherwise. | |
174 | .TP 5 | |
175 | TRANSFER chunked | |
176 | Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked" | |
177 | header. | |
178 | .TP 5 | |
179 | TRANSFER length | |
180 | Specifies that this test will use the HTTP/1.0 "Content-Length:" header. | |
181 | .TP 5 | |
182 | VERSION 1.0 | |
183 | .TP 5 | |
184 | VERSION 1.1 | |
185 | .TP 5 | |
186 | VERSION 2.0 | |
187 | .TP 5 | |
188 | VERSION 2.1 | |
189 | .TP 5 | |
190 | VERSION 2.2 | |
191 | Specifies the IPP version number to use for this test. | |
192 | ||
193 | .SH EXPECT PREDICATES | |
194 | The following predicates are understood following the EXPECT test directive: | |
195 | .TP 5 | |
196 | COUNT number | |
197 | Requires the EXPECT attribute to have the specified number of values. | |
198 | .TP 5 | |
199 | IF-DEFINED variable-name | |
200 | Makes the EXPECT conditions apply only if the specified variable is defined. | |
201 | .TP 5 | |
202 | IF-UNDEFINED variable-name | |
203 | Makes the EXPECT conditions apply only if the specified variable is not | |
204 | defined. | |
205 | .TP 5 | |
206 | IN-GROUP tag | |
207 | Requires the EXPECT attribute to be in the specified group tag. | |
208 | .TP 5 | |
209 | OF-TYPE tag[,tag,...] | |
210 | Requires the EXPECT attribute to use the specified value tag(s). | |
211 | .TP 5 | |
212 | SAME-COUNT-AS attribute-name | |
213 | Requires the EXPECT attribute to have the same number of values as the specified | |
214 | parallel attribute. | |
215 | .TP 5 | |
216 | WITH-VALUE "literal string" | |
217 | Requires at least one value of the EXPECT attribute to match the literal string. | |
218 | Comparisons are case-sensitive. | |
219 | .TP 5 | |
220 | WITH-VALUE "/regular expression/" | |
221 | Requires that all values of the EXPECT attribute match the regular expression, | |
222 | which must conform to the POSIX regular expression syntax. | |
223 | Comparisons are case-sensitive. | |
224 | ||
225 | .SH STATUS PREDICATES | |
226 | The following predicates are understood following the STATUS test directive: | |
227 | .TP 5 | |
228 | IF-DEFINED variable-name | |
229 | Makes the STATUS apply only if the specified variable is defined. | |
230 | .TP 5 | |
231 | IF-UNDEFINED variable-name | |
232 | Makes the STATUS apply only if the specified variable is not defined. | |
233 | ||
234 | .SH OPERATION CODES | |
235 | Operation codes correspond to the names from RFC 2911 and other IPP extension | |
236 | specifications. Here is a complete list: | |
237 | .nf | |
238 | Activate-Printer | |
239 | CUPS-Accept-Jobs | |
240 | CUPS-Add-Modify-Class | |
241 | CUPS-Add-Modify-Printer | |
242 | CUPS-Authenticate-Job | |
243 | CUPS-Delete-Class | |
244 | CUPS-Delete-Printer | |
245 | CUPS-Get-Classes | |
246 | CUPS-Get-Default | |
247 | CUPS-Get-Devices | |
248 | CUPS-Get-Document | |
249 | CUPS-Get-PPD | |
250 | CUPS-Get-PPDs | |
251 | CUPS-Get-Printers | |
252 | CUPS-Move-Job | |
253 | CUPS-Reject-Jobs | |
254 | CUPS-Set-Default | |
255 | Cancel-Current-Job | |
256 | Cancel-Job | |
257 | Cancel-Subscription | |
258 | Create-Job | |
259 | Create-Job-Subscription | |
260 | Create-Printer-Subscription | |
261 | Deactivate-Printer | |
262 | Disable-Printer | |
263 | Enable-Printer | |
264 | Get-Job-Attributes | |
265 | Get-Jobs | |
266 | Get-Notifications | |
267 | Get-Printer-Attributes | |
268 | Get-Printer-Support-Files | |
269 | Get-Printer-Supported-Values | |
270 | Get-Subscription-Attributes | |
271 | Get-Subscriptions | |
272 | Hold-Job | |
273 | Hold-New-Jobs | |
274 | Pause-Printer | |
275 | Pause-Printer-After-Current-Job | |
276 | Print-Job | |
277 | Print-URI | |
278 | Promote-Job | |
279 | Purge-Jobs | |
280 | Release-Held-New-Jobs | |
281 | Release-Job | |
282 | Renew-Subscription | |
283 | Reprocess-Job | |
284 | Restart-Job | |
285 | Restart-Printer | |
286 | Resume-Job | |
287 | Resume-Printer | |
288 | Schedule-Job-After | |
289 | Send-Document | |
290 | Send-Notifications | |
291 | Send-URI | |
292 | Set-Job-Attributes | |
293 | Set-Printer-Attributes | |
294 | Shutdown-Printer | |
295 | Startup-Printer | |
296 | Suspend-Current-Job | |
297 | Validate-Job | |
298 | .fi | |
299 | ||
300 | .SH STATUS CODES | |
301 | Status codes correspond to the names from RFC 2911 and other IPP extension | |
302 | specifications. Here is a complete list: | |
303 | .nf | |
304 | client-error-attributes-not-settable | |
305 | client-error-attributes-or-values-not-supported | |
306 | client-error-bad-request | |
307 | client-error-charset-not-supported | |
308 | client-error-compression-error | |
309 | client-error-compression-not-supported | |
310 | client-error-conflicting-attributes | |
311 | client-error-document-access-error | |
312 | client-error-document-format-error | |
313 | client-error-document-format-not-supported | |
314 | client-error-forbidden | |
315 | client-error-gone | |
316 | client-error-ignored-all-notifications | |
317 | client-error-ignored-all-subscriptions | |
318 | client-error-not-authenticated | |
319 | client-error-not-authorized | |
320 | client-error-not-found | |
321 | client-error-not-possible | |
322 | client-error-print-support-file-not-found | |
323 | client-error-request-entity-too-large | |
324 | client-error-request-value-too-long | |
325 | client-error-timeout | |
326 | client-error-too-many-subscriptions | |
327 | client-error-uri-scheme-not-supported | |
328 | cups-see-other | |
329 | redirection-other-site | |
330 | server-error-busy | |
331 | server-error-device-error | |
332 | server-error-internal-error | |
333 | server-error-job-canceled | |
334 | server-error-multiple-document-jobs-not-supported | |
335 | server-error-not-accepting-jobs | |
336 | server-error-operation-not-supported | |
337 | server-error-printer-is-deactivated | |
338 | server-error-service-unavailable | |
339 | server-error-temporary-error | |
340 | server-error-version-not-supported | |
341 | successful-ok | |
342 | successful-ok-but-cancel-subscription | |
343 | successful-ok-conflicting-attributes | |
344 | successful-ok-events-complete | |
345 | successful-ok-ignored-notifications | |
346 | successful-ok-ignored-or-substituted-attributes | |
347 | successful-ok-ignored-subscriptions | |
348 | successful-ok-too-many-events | |
349 | .fi | |
350 | ||
351 | .SH TAGS | |
352 | Value and group tags correspond to the names from RFC 2911 and other IPP | |
353 | extension specifications. Here are the group tags: | |
354 | .nf | |
355 | event-notification-attributes-tag | |
356 | job-attributes-tag | |
357 | operation-attributes-tag | |
358 | printer-attributes-tag | |
359 | subscription-attributes-tag | |
360 | unsupported-attributes-tag | |
361 | .fi | |
362 | .LP | |
363 | Here are the value tags: | |
364 | .nf | |
365 | admin-define | |
366 | boolean | |
367 | charset | |
368 | collection | |
369 | dateTime | |
370 | default | |
371 | delete-attribute | |
372 | enum | |
373 | integer | |
374 | keyword | |
375 | mimeMediaType | |
376 | nameWithLanguage | |
377 | nameWithoutLanguage | |
378 | naturalLanguage | |
379 | no-value | |
380 | not-settable | |
381 | octetString | |
382 | rangeOfInteger | |
383 | resolution | |
384 | textWithLanguage | |
385 | textWithoutLanguage | |
386 | unknown | |
387 | unsupported | |
388 | uri | |
389 | uriScheme | |
390 | .fi | |
391 | ||
392 | .SH VARIABLES | |
393 | The \fIipptest\fR program maintains a list of variables that can be used in any | |
394 | literal string or attribute value by specifying "$variable-name". Aside from | |
395 | variables defined using the "-d" option or "DEFINE" directive, the following | |
396 | pre-defined variables are available: | |
397 | .TP 5 | |
398 | $$ | |
399 | Inserts a single "$" character. | |
400 | .TP 5 | |
401 | $ENV[name] | |
402 | Inserts the value of the named environment variable, or an empty string if the | |
403 | environment variable is not defined. | |
404 | .TP 5 | |
405 | $filename | |
406 | Inserts the filename provided to \fIipptest\fR with the "-f" option. | |
407 | .TP 5 | |
408 | $hostname | |
409 | Inserts the hostname from the URI provided to \fIipptest\fR. | |
410 | .TP 5 | |
411 | $job-id | |
412 | Inserts the last job-id value returned in a test response or 0 if no job-id has | |
413 | been seen. | |
414 | .TP 5 | |
415 | $job-uri | |
416 | Inserts the last job-uri value returned in a test response or an empty string if | |
417 | no job-uri has been seen. | |
418 | .TP 5 | |
419 | $scheme | |
420 | Inserts the scheme from the URI provided to \fIipptest\fR. | |
421 | .TP 5 | |
422 | $notify-subscription-id | |
423 | Inserts the last notify-subscription-id value returnd in a test response or 0 if | |
424 | no notify-subscription-id has been seen. | |
425 | .TP 5 | |
426 | $port | |
427 | Inserts the port number from the URI provided to \fIipptest\fR. | |
428 | .TP 5 | |
429 | $resource | |
430 | Inserts the resource path from the URI provided to \fIipptest\fR. | |
431 | .TP 5 | |
432 | $uri | |
433 | Inserts the URI provided to \fIipptest\fR. | |
434 | .TP 5 | |
435 | $user | |
436 | Inserts the current user's login name. | |
437 | .TP 5 | |
438 | $username | |
439 | Inserts the username from the URI provided to \fIipptest\fR, if any. | |
440 | ||
441 | .SH SEE ALSO | |
442 | \fIipptest(1)\fR, | |
443 | .br | |
444 | http://localhost:631/help | |
445 | ||
446 | .SH COPYRIGHT | |
447 | Copyright 2007-2010 by Apple Inc. | |
448 | .\" | |
449 | .\" End of "$Id$". | |
450 | .\" |