Tester/Manual.pm untested

filter: Statementstmt 0.0% 0 / 1 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 0.0% 0 / 1 SCAR -
1 package JMAP::Tester::Manual 0.113;
2 # ABSTRACT: how to use JMAP::Tester
3  
4 #pod =head1 OVERVIEW
5 #pod
6 #pod JMAP::Tester is a simple JMAP client designed for testing, although it can
7 #pod certainly be used outside of tests. It's meant to be easy to use without a lot
8 #pod of training, but it's not so simple that you don't need a little bit of
9 #pod up-front knowledge. This document is meant to give a high-level overview of
10 #pod how to use it, with links to more detailed information as needed. Quite
11 #pod possibly, you won't need to click even one of them.
12 #pod
13 #pod =head2 Return types and asynchrony
14 #pod
15 #pod When using a JMAP::Tester, you'll need to know whether it was configured to run
16 #pod synchronously or asynchronously. You can check the result of calling
17 #pod C<< L<JMAP::Tester/should_return_futures> >>, but really you want to know this
18 #pod while writing your code, so just make sure you pay attention to how the object
19 #pod was constructed. If your tester returns futures, then its async methods return
20 #pod Future objects and can be called with C<await>. Otherwise, they will block and
21 #pod return whatever the future would have resolved to.
22 #pod
23 #pod The default behavior is to I<not> return futures, as most test suites are
24 #pod synchronous.
25 #pod
26 #pod Methods generally return an object that does the
27 #pod L<HTTPResult|JMAP::Tester::Role::HTTPResult> role, which has just a few
28 #pod important methods:
29 #pod
30 #pod =for :list
31 #pod * C<is_success>, which returns true for a successful HTTP response and false otherwise
32 #pod * C<http_response>, which returns the L<HTTP::Response> object for the result
33 #pod * C<response_payload>, which returns the HTTP response as a string
34 #pod
35 #pod =head2 Authentication and session
36 #pod
37 #pod JMAP does not specify authentication, so authenticating your tester is up to
38 #pod you. Most often, you do that by setting a default header on the tester's user
39 #pod agent, like this:
40 #pod
41 #pod my $tester = JMAP::Tester->new( ... );
42 #pod $tester->ua->set_default_header(Authorization => 'Bearer 1234');
43 #pod
44 #pod This is a pretty broad brush, but for testing your local test system, generally
45 #pod fine.
46 #pod
47 #pod The other thing associated with authentication is your JMAP session, which
48 #pod describes your account's capabilities and HTTP endpoints. The session object
49 #pod is generally represented as a L<JMAP::Tester::Result::Auth> object, which has
50 #pod one useful method: C<client_session>, which returns the decoded JSON structure
51 #pod of the session.
52 #pod
53 #pod There are a few methods for dealing with the session:
54 #pod
55 #pod =for :list
56 #pod * C<< L<JMAP::Tester/get_client_session> >>, an async method that fetches and
57 #pod returns the session object; on success, it returns an Auth object
58 #pod * C<< L<JMAP::Tester/update_client_session> >>, an async method that gets the
59 #pod client session, uses it to reconfigure the tester (if necessary), and returns
60 #pod the Auth object
61 #pod
62 #pod =head2 API requests
63 #pod
64 #pod The most common thing you'll do with a tester is probably make API requests.
65 #pod Those are the ones defined in L<RFC 8620
66 #pod §3.1|https://datatracker.ietf.org/doc/html/rfc8620#section-3.1> -- the ones
67 #pod with C<methodCalls>, where you do most of the work of JMAP.
68 #pod
69 #pod You call it like this:
70 #pod
71 #pod my $res = $tester->request({
72 #pod using => [ 'urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail' ],
73 #pod methodCalls => [ [ 'Some/method', { ... }, 'a' ], ... ],
74 #pod });
75 #pod
76 #pod If you trust the client's C<default_using>, provided during creation, you can
77 #pod skip the outer hashref and just provide an arrayref, which will be used as the
78 #pod C<methodCalls> value. Each entry in that arrayref is itself an arrayref that
79 #pod becomes the C<Invocation> (in RFC 8620 terms) that's passed to the remote API.
80 #pod If you don't include a method call id, the third element in the array, one will
81 #pod be generated for you.
82 #pod
83 #pod C<request> is an async method, and on success returns a
84 #pod L<Response|JMAP::Tester::Response> object. Since a I<lot> of testing your JMAP
85 #pod server involves inspecting API responses, it's important to know the interface!
86 #pod First, some jargon: a I<sentence> is one entry in the C<methodResponses>
87 #pod array; a I<paragraph> is a group of sequential sentences all sharing the same
88 #pod method call id. The first element in a sentence is its I<name>. Almost
89 #pod always, you'll be working with the sentences in a response, usually looked up
90 #pod by name.
91 #pod
92 #pod Here are the most important methods on a Response:
93 #pod
94 #pod =for :list
95 #pod * C<sentence($n)> returns the I<n>th sentence in the response (or dies if out
96 #pod of bounds)
97 #pod * C<sentence_named($name)> returns the sentence with this name (or dies if
98 #pod there isn't exactly one with that name)
99 #pod * C<single_sentence($name)> dies unless there is exactly one sentence in the
100 #pod response; if C<$name> is given, the method dies unless the sentence has that
101 #pod name; if it doesn't die, it returns that sentence.
102 #pod * C<as_pairs> and C<as_triples> return arrayrefs where each element is a 2- or
103 #pod 3-element arrayref of the name, arguments, and (maybe) client id of each
104 #pod sentence -- in other words, a plain structure representing the method
105 #pod response
106 #pod * C<as_stripped_pairs> and C<as_stripped_triples> return the same, but with
107 #pod L<JSON::Typist> data tripped from the arguments
108 #pod
109 #pod L<Sentence|JMAP::Tester::Response::Sentence> objects have these useful methods:
110 #pod
111 #pod =for :list
112 #pod * C<name> returns the sentence name
113 #pod * C<arguments> returns the sentence arguments
114 #pod * C<client_id> returns the method call id
115 #pod * C<as_pair>, C<as_triple>, C<as_stripped_pair>, and C<as_stripped_triple>
116 #pod behave like the similarly-named methods on a Response, but just return the
117 #pod arrayref representing this sentence
118 #pod * C<as_set> returns a new L<Set|JMAP::Tester::Response::Sentence::Set> object,
119 #pod with extra methods for testing the response to C</set>-style methods
120 #pod
121 #pod A "Set" sentence has all the methods of a normal sentence as well as:
122 #pod
123 #pod =for :list
124 #pod * C<new_state> and C<old_state>: return the new and old state
125 #pod * C<created>: returns the C<created> argument, or an empty hashref if null
126 #pod * C<created_id($creation_id)>: returns the C<id> for the object created for
127 #pod that creation id
128 #pod * C<updated>: returns the C<updated> argument, or an empty hashref if null
129 #pod * C<created_ids>, C<updated_ids>, C<destroyed_ids>: return the ids of objects
130 #pod created, updated, or destroyed
131 #pod * C<create_errors>, C<update_errors>, C<destroy_errors>: return the errors with
132 #pod their respective operations, or an empty hashref if none
133 #pod * C<not_created_ids>, C<not_updated_ids>, C<not_destroyed_ids>: return the ids
134 #pod of objects not created, not updated, or not destroyed; in other words, the
135 #pod keys of the hashrefs returned by the error methods above
136 #pod
137 #pod There are also a few useful assertion-making methods to know. These will throw
138 #pod aborts (L<see below|/Diagnostics and logging>) if the condition they assert
139 #pod doesn't hold true:
140 #pod
141 #pod =for :list
142 #pod * C<< $result->assert_successful >>: the result must be a success
143 #pod (C<is_success> is true)
144 #pod * C<< $result->assert_successful_set($name) >>: the result must be an API
145 #pod request result with a sentence named C<$name>, which must be a C</set>
146 #pod method, and it must be reporting zero errors (like C<notCreated> etc.)
147 #pod * C<< $result->assert_single_successful_set($name) >>: just like the above, but
148 #pod there must be only one sentence in the response; C<$name> can be omitted to
149 #pod allow any C</set>
150 #pod * C<< $set->assert_no_errors >>: on a Set sentence, this asserts that there
151 #pod were no errors in any of its operations
152 #pod
153 #pod =head2 Uploads and downloads
154 #pod
155 #pod Testing blobs might require that you perform JMAP upload or download requests.
156 #pod For these, the C<< L<JMAP::Tester/upload> >> and C<< L<JMAP::Tester/download>
157 #pod >> methods exist.
158 #pod
159 #pod C<upload> takes as its argument a hashref of upload properties and on success
160 #pod returns an L<Upload|JMAP::Tester::Result::Upload> object. The argument hashref
161 #pod must contain:
162 #pod
163 #pod accountId - the account for which we're uploading (no default)
164 #pod type - the content-type we want to provide to the server
165 #pod blob - the data to upload. Must be a reference to a string
166 #pod
167 #pod C<download> takes as its argument a hashref of download properties and on
168 #pod success returns a L<Download|JMAP::Tester::Result::Download> object. The
169 #pod argument hashref must contain:
170 #pod
171 #pod blobId - the blob to download (no default)
172 #pod accountId - the account for which we're downloading (no default)
173 #pod type - the content-type we want the server to provide back (no default)
174 #pod name - the name we want the server to provide back (default: "download")
175 #pod
176 #pod =head2 Other HTTP requests
177 #pod
178 #pod Sometimes, you may need to make a custom HTTP request with the same underlying
179 #pod user agent as your tester uses. This might be to interact with a custom
180 #pod authentication mechanism, to access custom endpoints, or just to make very,
181 #pod very specifically crafted requests. For this reason, C<http_request> exists.
182 #pod It's an async method that takes an L<HTTP::Request> object as its argument and
183 #pod returns an L<HTTP::Response>. Remember when you make this call that the
184 #pod default headers you may have set up for auth will be applied!
185 #pod
186 #pod =head2 Diagnostics and logging
187 #pod
188 #pod Many of JMAP::Tester's failures are L<Test::Abortable> exceptions ("aborts")
189 #pod that can terminate subtests without terminating the whole test program. They
190 #pod provide useful diagnostics on failure, so learning and using the JMAP::Tester
191 #pod methods that die on unexpected results can save you time later.
192 #pod
193 #pod Further, JMAP::Tester has a generic request logging system. It's subject to
194 #pod significant change, but the important thing to know is that if you set the
195 #pod C<JMAP_TESTER_LOGGER> environment variable to C<HTTP>, you'll end up with a
196 #pod file in the current working directory with a name like F<jmap-tester-….log>
197 #pod that contains the requests and responses made.
198 #pod
199 #pod =cut
200  
201 1;
202  
203 __END__