Adding documentation for servlet testing system

collects/web-server/scribblings/test.scrbl

@@ -1,7 +1,10 @@
 #lang scribble/doc
 @(require "web-server.rkt"
           (for-label web-server/http/request-structs
+                     web-server/servlet/servlet-structs
                      xml
+                     web-server/test
+                     net/url
                      racket/promise
                      racket/match))
 
@@ -20,10 +23,52 @@ The core functionality allows a request to be sent to the servlet and the respon
          (->* ()
               ((or/c string? url? request? false/c)
                (listof binding?)
-               boolean?)
+               #:raw? boolean?)
               (or/c bytes?
                     xexpr?))]{
  
-This function accepts 
+This function accepts a servlet function and provides a function that accepts a request and returns the answer the servlet for that request. This interaction function has many possible calling patterns:
-                              
+@itemize[
+ @item{No arguments: a call to the root URL path with no bindings.}
+ @item{At least one argument: this may be a string, URL, or a request data structure.}
+ @item{Two arguments: the first argument must be a string or a URL, but the second argument can specify the request bindings.}
+ @item{The optional @racket[#:raw?] keyword controls whether an X-expression or a byte string is returned as a result.}
+]
 }
+                             
+This facility is designed to be used in concert with a technique of extracting continuation URLs and relevant values; @racketmodname[xml/path] is one way to do this. Here is an extended example that tests an Add-Two-Numbers.com:
+@(require (for-label xml/path
+                     rackunit
+                     racket/list
+                     racket/promise))
+@racketblock[
+(define (test-add-two-numbers -s>)
+  (define x (random 500))
+  (define xs (string->bytes/utf-8 (number->string x)))
+  (define y (random 500))
+  (define ys (string->bytes/utf-8 (number->string y)))
+  
+  (define r0 (-s>))
+  (define k0 (se-path* '(form #:action) r0))
+  (define i0 (se-path* '(form input #:name) r0))
+  (define r1 
+    (-s> (format "~a?~a=~a" k0 i0 xs)
+         (list (make-binding:form (string->bytes/utf-8 i0) xs))))
+  (define k1 (se-path* '(form #:action) r1))
+  (define i1 (se-path* '(form input #:name) r1))
+  (define r2 
+    (-s> (format "~a?~a=~a" k1 i1 ys)
+         (list (make-binding:form (string->bytes/utf-8 i1) ys))))
+  (define n (se-path* '(p) r2))
+  (check-equal? n
+                (format "The answer is ~a" (+ x y))))
+
+(require
+ (prefix-in ex:add1: web-server/default-web-root/htdocs/servlets/examples/add)
+ (prefix-in ex:add2: web-server/default-web-root/htdocs/servlets/examples/add-v2))
+
+(test-add-two-numbers 
+ (make-servlet-tester ex:add1:start))
+(test-add-two-numbers 
+ (make-servlet-tester ex:add2:start))
+]

collects/web-server/scribblings/web-server.scrbl

@@ -16,7 +16,7 @@ This manual describes the Racket libraries for building Web applications.
 The @secref["http"] section describes the common library function for manipulating HTTP requests and creating HTTP responses.
 In particular, this section covers cookies, authentication, and request bindings.
 
-The final four sections (@secref["dispatch"], @secref["formlets"], @secref["templates"], and @secref["page"]) cover utility libraries that ease the creation of typical Web applications.
+The final five sections (@secref["dispatch"], @secref["formlets"], @secref["templates"], @secref["page"], and @secref["test"]) cover utility libraries that ease the creation of typical Web applications.
 
 This manual closes with a frequently asked questions section: @secref["faq"].