| 1 | package Dredd::Hooks::Methods; | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | Dredd::Hooks::Methods - Sugar module for each of writing Dredd Hookfiles | ||
| 6 | |||
| 7 | =head1 SUMMARY | ||
| 8 | |||
| 9 | #!/usr/bin/env perl | ||
| 10 | # hookfiles.pl | ||
| 11 | |||
| 12 | use strict; | ||
| 13 | use warnings; | ||
| 14 | |||
| 15 | use Dredd::Hooks::Methods; | ||
| 16 | |||
| 17 | before('/messages > GET' => sub { | ||
| 18 | my ($transaction) = @_; | ||
| 19 | |||
| 20 | $transaction->{headers}{RawData}{Auth} = 'Basic: hud87y2h8o7ysdiuhlku12h==' | ||
| 21 | }); | ||
| 22 | |||
| 23 | =head1 DESCRIPTION | ||
| 24 | |||
| 25 | Dredd::Hooks::Methods provides useful functions for writing | ||
| 26 | Dredd hook files. | ||
| 27 | |||
| 28 | L<Dredd|https://dredd.readthedocs.org> is a testing framework | ||
| 29 | for testing API BluePrint formatted API definition files | ||
| 30 | against the implemenation that exposes that API. This is useful | ||
| 31 | to ensure that the API documentation doesn't get out of sync | ||
| 32 | with an new code changes. | ||
| 33 | |||
| 34 | L<Dredd::Hooks> provides and implementation of the | ||
| 35 | L<Dredd hooks handler socket interface|https://dredd.readthedocs.org/en/latest/hooks-new-language/> | ||
| 36 | and ensures that hooks from user defined hook files are run in | ||
| 37 | the correct order and with the correct information. | ||
| 38 | |||
| 39 | Dredd::Hooks::Methods provides functionallity that allow the | ||
| 40 | user to define the hooks files that get run and their | ||
| 41 | functionality. | ||
| 42 | |||
| 43 | =head1 Creating a hook file | ||
| 44 | |||
| 45 | Hookfiles are plain .pl perl files containing some callbacks | ||
| 46 | that are run for specific events. | ||
| 47 | |||
| 48 | The hookfile should have a .pl file extention (required by the | ||
| 49 | dredd funtion and are provided as an argument to the dredd code: | ||
| 50 | |||
| 51 | C<dredd apiary.apib http://localhost:5000 --language perl --hookfiles=./hooks/hooks_*.pl> | ||
| 52 | |||
| 53 | for each event listed in the Dredd documentation a method is | ||
| 54 | provided that takes a sub ref that will be run for that event, | ||
| 55 | This event will receive a transaction (HashRef) or an arrayref of | ||
| 56 | transactions that it should modify in place. The return value of this | ||
| 57 | function will be ignored: | ||
| 58 | |||
| 59 | beforeAll(sub { | ||
| 60 | my ($transactions) = @_; | ||
| 61 | }); | ||
| 62 | |||
| 63 | beforeEach(sub { | ||
| 64 | my ($transaction) = @_; | ||
| 65 | }); | ||
| 66 | |||
| 67 | See the each event below for the which events take which arguments. | ||
| 68 | If multiple callbacks are defined for the same event then these will | ||
| 69 | be run individually in the order defined. e.g: | ||
| 70 | |||
| 71 | beforeAll(sub { | ||
| 72 | ... # Run First | ||
| 73 | }); | ||
| 74 | |||
| 75 | beforeAll(sub { | ||
| 76 | ... # Run Second | ||
| 77 | }); | ||
| 78 | |||
| 79 | You can also supply multiple files (or a glob) to the dredd command | ||
| 80 | and these will all be coallated together. Allowing spefic hooks for | ||
| 81 | specific transactions or event types. | ||
| 82 | |||
| 83 | All events are run in a specific order: | ||
| 84 | |||
| 85 | beforeAll - Run before all transactions | ||
| 86 | beforeEach - Run before each transaction | ||
| 87 | before - Run before specific transactions | ||
| 88 | beforeEachValidation - Run before each Validation step | ||
| 89 | beforeValidation - Run before a specific validation step | ||
| 90 | after - Run after a specific transaction | ||
| 91 | afterEach - Run after each transaction | ||
| 92 | afterAll - Run after all transactions | ||
| 93 | |||
| 94 | =cut | ||
| 95 | |||
| 96 | 1 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 97 | 1 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 98 | |||
| 99 | 1 | ▶ | use Hash::Merge; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 100 | 1 | ▶ | use Sub::Exporter -setup => { |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 101 | exports => [qw/ | ||
| 102 | before | ||
| 103 | beforeAll | ||
| 104 | beforeEach | ||
| 105 | beforeEachValidation | ||
| 106 | beforeValidation | ||
| 107 | after | ||
| 108 | afterAll | ||
| 109 | afterEach | ||
| 110 | get_hooks | ||
| 111 | merge_hook | ||
| 112 | /], | ||
| 113 | groups => { | ||
| 114 | default => [qw/ | ||
| 115 | before | ||
| 116 | beforeAll | ||
| 117 | beforeEach | ||
| 118 | beforeEachValidation | ||
| 119 | beforeValidation | ||
| 120 | after | ||
| 121 | afterAll | ||
| 122 | afterEach | ||
| 123 | /], | ||
| 124 | handler => [qw/ | ||
| 125 | get_hooks | ||
| 126 | merge_hook | ||
| 127 | /] | ||
| 128 | } | ||
| 129 | 1 | }; | |
| 130 | |||
| 131 | { | ||
| 132 | 1 | my $hooks = {}; | |
| 133 | 0 | ▶ | sub get_hooks { |
|
Subroutine
get_hooks: not called CC=1 SCAR=6.9
Pod
undocumented
| |||
| 134 | 0 | return $hooks; | |
| 135 | } | ||
| 136 | |||
| 137 | 1 | my $merger = Hash::Merge->new('RETAINMENT_PRECEDENT'); | |
| 138 | 0 | ▶ | sub merge_hook { |
|
Subroutine
merge_hook: not called CC=1 SCAR=6.9
Pod
undocumented
| |||
| 139 | 0 | my ($hook) = @_; | |
| 140 | |||
| 141 | 0 | $hooks = $merger->merge($hooks, $hook); | |
| 142 | } | ||
| 143 | } | ||
| 144 | |||
| 145 | =head1 Events | ||
| 146 | |||
| 147 | =head2 beforeAll (callback Sub) | ||
| 148 | |||
| 149 | The beforeAll event is triggered before all transactions | ||
| 150 | are run. As such it is an ideal place to run test setup code. | ||
| 151 | |||
| 152 | The hook will receive an array of transaction hashrefs | ||
| 153 | representing each transaction that will be implemented. | ||
| 154 | |||
| 155 | =cut | ||
| 156 | |||
| 157 | 1 | ▶ | sub beforeAll { |
|
Subroutine
beforeAll: not called CC=1 SCAR=2.6
Pod
documented
| |||
| 158 | 0 | my ($callback) = @_; | |
| 159 | |||
| 160 | 0 | merge_hook({beforeAll => $callback }); | |
| 161 | } | ||
| 162 | |||
| 163 | =head2 beforeEach (callback Sub) | ||
| 164 | |||
| 165 | The beforeEach event is called for before each transaction | ||
| 166 | is run. | ||
| 167 | |||
| 168 | The hook will receive a single transaction hashref. | ||
| 169 | |||
| 170 | NOTE: This event from Dredd triggers the before event | ||
| 171 | |||
| 172 | =cut | ||
| 173 | |||
| 174 | 0 | ▶ | sub beforeEach { |
|
Subroutine
beforeEach: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 175 | 0 | my ($callback) = @_; | |
| 176 | |||
| 177 | 0 | merge_hook({beforeEach => $callback }); | |
| 178 | } | ||
| 179 | |||
| 180 | =head2 before (name Str, callback Sub) | ||
| 181 | |||
| 182 | The before event is called for each transaction whose | ||
| 183 | name attribute matches that given in the hook creation. | ||
| 184 | |||
| 185 | The hook will receive a single transaction hashref. | ||
| 186 | |||
| 187 | NOTE: before is not actually and event called by Dredd | ||
| 188 | directly but it is called after the beforeEach event. | ||
| 189 | |||
| 190 | =cut | ||
| 191 | |||
| 192 | 0 | ▶ | sub before { |
|
Subroutine
before: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 193 | 0 | my ($name, $callback) = @_; | |
| 194 | |||
| 195 | 0 | merge_hook({before => { $name => $callback }}); | |
| 196 | } | ||
| 197 | |||
| 198 | =head2 beforeEachValidation (callback Sub) | ||
| 199 | |||
| 200 | The beforeEachValidation event is called for before each | ||
| 201 | transactions result is validated. | ||
| 202 | |||
| 203 | The hook will receive a single transaction hashref. | ||
| 204 | |||
| 205 | NOTE: This event is from Dredd triggers the beforeValidation event | ||
| 206 | |||
| 207 | =cut | ||
| 208 | |||
| 209 | 0 | ▶ | sub beforeEachValidation { |
|
Subroutine
beforeEachValidation: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 210 | 0 | my ($callback) = @_; | |
| 211 | |||
| 212 | 0 | merge_hook({beforeEachValidation => $callback }); | |
| 213 | } | ||
| 214 | |||
| 215 | =head2 beforeValidation (name Str, callback Sub) | ||
| 216 | |||
| 217 | The beforeEachValidation event is called for before the | ||
| 218 | validation of each transactions result, whose transaction | ||
| 219 | name matches the name supplied to this function, is validatated. | ||
| 220 | |||
| 221 | The hook will receive a single transaction hashref. | ||
| 222 | |||
| 223 | NOTE: beforeValidation is not actually and event called by Dredd | ||
| 224 | directly but it is called after the beforeEachValidation event. | ||
| 225 | |||
| 226 | =cut | ||
| 227 | |||
| 228 | 0 | ▶ | sub beforeValidation { |
|
Subroutine
beforeValidation: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 229 | 0 | my ($name, $callback) = @_; | |
| 230 | |||
| 231 | 0 | merge_hook({beforeValidation => { $name => $callback }}); | |
| 232 | } | ||
| 233 | |||
| 234 | =head2 after (name Str, callback Sub) | ||
| 235 | |||
| 236 | The after event is called after each transaction whose | ||
| 237 | name attribute matches that given in the hook creation. | ||
| 238 | |||
| 239 | The hook will receive a single transaction hashref. | ||
| 240 | |||
| 241 | NOTE: after is not actually and event called by Dredd | ||
| 242 | directly but it is called before the afterEach event. | ||
| 243 | |||
| 244 | =cut | ||
| 245 | |||
| 246 | 0 | ▶ | sub after { |
|
Subroutine
after: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 247 | 0 | my ($name, $callback) = @_; | |
| 248 | |||
| 249 | 0 | merge_hook({after => { $name => $callback }}); | |
| 250 | } | ||
| 251 | |||
| 252 | =head2 beforeEach (callback Sub) | ||
| 253 | |||
| 254 | The afterEach event is called for after each transaction | ||
| 255 | is run. | ||
| 256 | |||
| 257 | The hook will receive a single transaction hashref. | ||
| 258 | |||
| 259 | NOTE: This event from Dredd triggers the after event | ||
| 260 | |||
| 261 | =cut | ||
| 262 | |||
| 263 | 0 | ▶ | sub afterEach { |
|
Subroutine
afterEach: not called CC=1 SCAR=6.9
Pod
undocumented
| |||
| 264 | 0 | my ($callback) = @_; | |
| 265 | |||
| 266 | 0 | merge_hook({afterEach => $callback }); | |
| 267 | } | ||
| 268 | |||
| 269 | =head2 afterAll (callback Sub) | ||
| 270 | |||
| 271 | The afterAll event is triggers after all transactions are run. | ||
| 272 | As such it is an ideal place to run test teardown code. | ||
| 273 | |||
| 274 | The hook will receive an array of transaction hashrefs | ||
| 275 | representing each transaction that will be implemented. | ||
| 276 | |||
| 277 | =cut | ||
| 278 | |||
| 279 | 0 | ▶ | sub afterAll { |
|
Subroutine
afterAll: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 280 | 0 | my ($callback) = @_; | |
| 281 | |||
| 282 | 0 | merge_hook({afterAll => $callback }); | |
| 283 | } | ||
| 284 | 1 | 1; | |
| 285 | __END__ | ||