| 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__ |