| 1 |
NAME |
| 2 |
|
| 3 |
Fennec - A testers toolbox, and best friend |
| 4 |
|
| 5 |
DESCRIPTION |
| 6 |
|
| 7 |
Fennec ties together several testing related modules and enhances their |
| 8 |
functionality in ways you don't get loading them individually. Fennec |
| 9 |
makes testing easier, and more useful. |
| 10 |
|
| 11 |
CAVEAT EMPTOR |
| 12 |
|
| 13 |
This module is deprecated in favor of Test2::Suite, specifically |
| 14 |
Test2::Tools::Spec and Test2::Bundle::SpecDeclare. |
| 15 |
|
| 16 |
SYNOPSIS |
| 17 |
|
| 18 |
There are 2 ways to use Fennec. You can use Fennec directly, or you can |
| 19 |
use the shiny sugar-coated interface provided by the add-on module |
| 20 |
Fennec::Declare. |
| 21 |
|
| 22 |
VANILLA SYNTAX |
| 23 |
|
| 24 |
If Devel::Declare and its awesome power of syntax specification scares |
| 25 |
you, you can always write your Fennec tests in the stone age like |
| 26 |
this... just don't miss any semicolons. |
| 27 |
|
| 28 |
t/some_test.t: |
| 29 |
|
| 30 |
package TEST::SomeTest; |
| 31 |
use strict; |
| 32 |
use warnings; |
| 33 |
|
| 34 |
use Fennec( |
| 35 |
parallel => 3, |
| 36 |
test_sort => 'random', |
| 37 |
); |
| 38 |
|
| 39 |
# This is optional, there is a default 'new' if you do not override it. |
| 40 |
sub new { ... } |
| 41 |
|
| 42 |
# Test blocks are called as methods on an instance of your test package. |
| 43 |
tests group_1 => sub { |
| 44 |
my $self = shift; |
| 45 |
ok( 1, "1 is true" ); |
| 46 |
}; |
| 47 |
|
| 48 |
test group_2 => ( |
| 49 |
todo => 'This is not ready yet', |
| 50 |
code => sub { |
| 51 |
my $self = shift; |
| 52 |
ok( 0, "Not ready" ); |
| 53 |
} |
| 54 |
); |
| 55 |
|
| 56 |
# It is important to always end a Fennec test with this function call. |
| 57 |
done_testing(); |
| 58 |
|
| 59 |
DECLARE SYNTAX |
| 60 |
|
| 61 |
Note: In order to use this you MUST install Fennec::Declare which is a |
| 62 |
separate distribution on cpan. This module is separate because it uses |
| 63 |
the controversial Devel::Declare module. |
| 64 |
|
| 65 |
t/some_test.t: |
| 66 |
|
| 67 |
package TEST::SomeTest; |
| 68 |
use strict; |
| 69 |
use warnings; |
| 70 |
|
| 71 |
use Fennec::Declare( |
| 72 |
parallel => 3, |
| 73 |
test_sort => 'random', |
| 74 |
); |
| 75 |
|
| 76 |
# This is optional, there is a default 'new' if you do not override it. |
| 77 |
sub new { ... } |
| 78 |
|
| 79 |
# Test blocks are called as methods on an instance of your test package. |
| 80 |
tests group_1 { |
| 81 |
# Note: $self is automatically shifted for you. |
| 82 |
ok( $self, "Got self automatically" ); |
| 83 |
}; |
| 84 |
|
| 85 |
test group_2 ( todo => 'This is not ready yet' ) { |
| 86 |
# Note: $self is automatically shifted for you. |
| 87 |
ok( 0, "Not ready" ); |
| 88 |
} |
| 89 |
|
| 90 |
# It is important to always end a Fennec test with this function call. |
| 91 |
done_testing; |
| 92 |
|
| 93 |
FEATURES |
| 94 |
|
| 95 |
PROVIDED DIRECTLY BY FENNEC |
| 96 |
|
| 97 |
Forking just works |
| 98 |
|
| 99 |
Forking in perl tests that use Test::Builder is perilous at best. |
| 100 |
Fennec initiates an Fennec::Collector class which sets up |
| 101 |
Test::Builder to funnel all test results to the main thread for |
| 102 |
rendering. A result of this is that forking just works. |
| 103 |
|
| 104 |
Concurrency, test blocks can run in parallel |
| 105 |
|
| 106 |
By default all test blocks are run in parallel with a cap of 3 |
| 107 |
concurrent processes. The process cap can be set with the parallel |
| 108 |
import argument. |
| 109 |
|
| 110 |
No need to maintain a test count |
| 111 |
|
| 112 |
The test count traditionally was used to ensure your file finished |
| 113 |
running instead of exiting silently too early. With Test::Builder and |
| 114 |
friends this has largely been replaced with the done_testing() |
| 115 |
function typically called at the end of tests. Fennec shares this |
| 116 |
concept, but takes it further, you MUST call done_testing() at the |
| 117 |
end of your test files. This is safer because it can be used to |
| 118 |
ensure your test script ran completely. |
| 119 |
|
| 120 |
Can be decoupled from Test::Builder |
| 121 |
|
| 122 |
Fennec is built with the assumption that Test::Builder and tools |
| 123 |
built from it will be used. However custom Fennec::Collector and |
| 124 |
Fennec::Runner classes can replace this assumption with any testing |
| 125 |
framework you want to use. |
| 126 |
|
| 127 |
Can run specific test blocks, excluding others |
| 128 |
|
| 129 |
Have you ever had a huge test that took a long time to run? Have you |
| 130 |
ever needed to debug a failing test at the end of the file? How many |
| 131 |
times did you need to sit through tests that didn't matter? |
| 132 |
|
| 133 |
With Fennec you can specify the FENNEC_TEST environment variable with |
| 134 |
either a line number or test block name. Only tests defined on that |
| 135 |
line, or with that name will be run. |
| 136 |
|
| 137 |
Predictability: Rand is always seeded with the date |
| 138 |
|
| 139 |
Randomizing the order in which test blocks are run can help find |
| 140 |
subtle interaction bugs. At the same time if tests are always in |
| 141 |
random order you cannot reliably reproduce a failure. |
| 142 |
|
| 143 |
Fennec always seeds rand with the current date. This means that on |
| 144 |
any given date the test run order will always be the same. However |
| 145 |
different days test different orders. You can always specify the |
| 146 |
FENNEC_SEED environment variable to override the value used to seed |
| 147 |
rand. |
| 148 |
|
| 149 |
Diag output is coupled with test output |
| 150 |
|
| 151 |
When you run a Fennec test with a verbose harness (prove -v) the |
| 152 |
diagnostic output will be coupled with the TAP output. This is done |
| 153 |
by sending both output to STDOUT. In a non-verbose harness the |
| 154 |
diagnostics will be sent to STDERR per usual. |
| 155 |
|
| 156 |
Works with Moose |
| 157 |
|
| 158 |
All your test classes are instantiated objects. You can use Moose to |
| 159 |
define these test classes. But you do not have to, you are not forced |
| 160 |
to use OOP in your tests. |
| 161 |
|
| 162 |
PROVIDED BY MODULES LOADED BY FENNEC |
| 163 |
|
| 164 |
The 3 most common and useful Test::* modules |
| 165 |
|
| 166 |
Test::More, Test::Warn, Test::Exception |
| 167 |
|
| 168 |
RSPEC support |
| 169 |
|
| 170 |
Those familiar with Ruby may already know about the RSPEC testing |
| 171 |
process. In general you describe something that is to be tested, then |
| 172 |
you define setup and teardown methods (before_all, before_each, |
| 173 |
after_all, after_each) and then finally you test it. See the |
| 174 |
"EXAMPLES" section or Test::Workflow for more details. |
| 175 |
|
| 176 |
Test re-ordering, tests can run in random, sorted, or defined order. |
| 177 |
|
| 178 |
When you load Fennec you can specify a test order. The default is |
| 179 |
random. You can also use the order in which they are defined, or |
| 180 |
sorted (alphabetically) order. If necessary you can pass in a sorting |
| 181 |
function that takes a list of all test-objects as arguments. |
| 182 |
|
| 183 |
Provided by Test::Workflow |
| 184 |
|
| 185 |
Reusable test modules |
| 186 |
|
| 187 |
You can write tests in modules using Test::Workflow and then import |
| 188 |
those tests into Fennec tests. This is useful if you have tests that |
| 189 |
you want run in several, or even all test files. |
| 190 |
|
| 191 |
Provided by Test::Workflow |
| 192 |
|
| 193 |
Incredibly powerful mocking with a simple API |
| 194 |
|
| 195 |
You can create classless object instances from a specification on the |
| 196 |
fly, define new packages, or override existing packages. |
| 197 |
|
| 198 |
Provided by Mock::Quick |
| 199 |
|
| 200 |
DEFAULT IMPORTED MODULES |
| 201 |
|
| 202 |
Note: These can be overridden either on import, or by subclassing |
| 203 |
Fennec. |
| 204 |
|
| 205 |
Child - Forking for dummies |
| 206 |
|
| 207 |
Child is an OO interface to forking that removes all the boilderplate |
| 208 |
such as checking if the pid changed, and making sure you exit the |
| 209 |
child process. |
| 210 |
|
| 211 |
Mock::Quick - Mocking without the eye gouging |
| 212 |
|
| 213 |
Mock::Quick is a mocking library that makes mocking easy. In addition |
| 214 |
it uses a declarative style interface. Unlike most other mocking |
| 215 |
libraries on CPAN, it does not make people want to gouge their eyes |
| 216 |
out and curl up in the fetal position. |
| 217 |
|
| 218 |
Test::Workflow - RSPEC for perl. |
| 219 |
|
| 220 |
Test::Workflow is a testing library written specifically for Fennec. |
| 221 |
This library provides RSPEC workflow functions and structure. It can |
| 222 |
be useful on its own, but combined with Fennec it gets concurrency. |
| 223 |
|
| 224 |
Test::More |
| 225 |
|
| 226 |
Tried and True testing module that everyone uses. |
| 227 |
|
| 228 |
Test::Warn |
| 229 |
|
| 230 |
Test::Warn - Test code that issues warnings. |
| 231 |
|
| 232 |
Test::Exception |
| 233 |
|
| 234 |
Test::Exception - Test code that throws exceptions |
| 235 |
|
| 236 |
IMPORT ARGUMENTS |
| 237 |
|
| 238 |
base => 'Some::Base' |
| 239 |
|
| 240 |
Load the specified module and make it the base class for your test |
| 241 |
class. |
| 242 |
|
| 243 |
class => 'What::To::Test' |
| 244 |
|
| 245 |
Used to specify the name of the package your test file is validating. |
| 246 |
When this parameter is specified 3 things are done for you: The class |
| 247 |
is automatically loaded, the $CLASS variable is imported and contains |
| 248 |
the module name, and the class() subroutine is defined and returns |
| 249 |
the name. |
| 250 |
|
| 251 |
use Fennec class => 'Foo::Bar'; |
| 252 |
|
| 253 |
ok( $INC{'Foo/Bar.pm'}, "Loaded 'Foo::Bar'" ); |
| 254 |
is( $CLASS, 'Foo::Bar', "We have \$CLASS" ); |
| 255 |
is( class(), 'Foo::Bar', "We have class()" ); |
| 256 |
|
| 257 |
tests method => sub { |
| 258 |
my $self = shift; |
| 259 |
is( $self->class(), 'Foo::Bar', "We have class() method" ); |
| 260 |
}; |
| 261 |
|
| 262 |
done_testing; |
| 263 |
|
| 264 |
parallel => $PROC_LIMIT |
| 265 |
|
| 266 |
How many test blocks can be run in parallel. Default is 3. Set to 1 |
| 267 |
to fork for each test, but only run one at a time. Set to 0 to |
| 268 |
prevent forking. |
| 269 |
|
| 270 |
You can also set this using the $FENNEC_PARALLEL environment |
| 271 |
variable. |
| 272 |
|
| 273 |
debug => 1 |
| 274 |
|
| 275 |
Enable tracking debugging information. At the end of the Fennec run |
| 276 |
it will present you with a CSV temp file. This file lists all blocks |
| 277 |
that are run, and mocks that are made in sequence from top to bottom. |
| 278 |
The actions are split into columns by PID. This is usedul when |
| 279 |
debugging potential race-conditions when using parallel testing. |
| 280 |
|
| 281 |
Example: |
| 282 |
|
| 283 |
26150,26151,26152,26153,26154 |
| 284 |
0 26150 BLOCK 54->78 child: outer_wrap, , , , , |
| 285 |
,1 26151 BLOCK 47->52 test: class_store, , , , |
| 286 |
0 26150 MOCK Foo => (outer), , , , , |
| 287 |
0 26150 BLOCK 58->61 before_all: ba, , , , , |
| 288 |
, ,2 26152 MOCK Foo => (outer), , , |
| 289 |
, ,2 26152 BLOCK 63->66 before_each: be, , , |
| 290 |
, ,2 26152 BLOCK 68->72 test: the_check, , , |
| 291 |
, , ,3 26153 BLOCK 16->31 test: object, , |
| 292 |
, , , ,4 26154 BLOCK 33->45 test: class, |
| 293 |
|
| 294 |
You can use this in a spreadsheet program, or use this command to |
| 295 |
look at it in a more friendly way. |
| 296 |
|
| 297 |
column -s, -t < '/path/to/tempfile' | less -#2 -S |
| 298 |
|
| 299 |
collector_class => 'Fennec::Collector::TB::TempFiles' |
| 300 |
|
| 301 |
Specify which collector to use. Defaults to a Test::Builder based |
| 302 |
collector that uses temp files to funnel tests from child procs to |
| 303 |
the parent. |
| 304 |
|
| 305 |
You generally won't need to specify this, unless you use a test |
| 306 |
infrastructure that is neither TAP nore Test::Builder based. |
| 307 |
|
| 308 |
runner_class => 'Fennec::Runner' |
| 309 |
|
| 310 |
Specify the runner class. You probably don't need this. |
| 311 |
|
| 312 |
runner_params => { ... } |
| 313 |
|
| 314 |
Lets you specify arguments used when Fennec::Runner is initialized. |
| 315 |
|
| 316 |
skip_without => [ 'Need::This', 'And::This' ] |
| 317 |
|
| 318 |
Tell Fennec to skip the test file if any of the specified modules are |
| 319 |
missing. |
| 320 |
|
| 321 |
test_sort => $SORT |
| 322 |
|
| 323 |
Options: 'random', 'sorted', 'ordered', or a code block. |
| 324 |
|
| 325 |
Code block accepts a list of Test::Workflow::Test objects. |
| 326 |
|
| 327 |
utils => [ 'Test::Foo', ... ] |
| 328 |
|
| 329 |
Load these modules instead of the default list. |
| 330 |
|
| 331 |
If you need to specify import arguments for any specific util class, |
| 332 |
you can use the class name as the key with an arrayref containing the |
| 333 |
arguments. |
| 334 |
|
| 335 |
use Fennec( |
| 336 |
utils => [ 'Some::Module' ], |
| 337 |
'Some::Module' => [ arg => $val, ... ], |
| 338 |
); |
| 339 |
|
| 340 |
with_tests => [ 'Reusable::Tests', 'Common::Tests' ] |
| 341 |
|
| 342 |
Load these modules that have reusable tests. Reusable tests are tests |
| 343 |
that are common to multiple test files. |
| 344 |
|
| 345 |
seed => '...' |
| 346 |
|
| 347 |
Set the random seed to be used. Defaults to current date, can be |
| 348 |
overridden by the FENNEC_SEED environment variable. |
| 349 |
|
| 350 |
ENVIRONMENT VARIABLES |
| 351 |
|
| 352 |
FENNEC_SEED |
| 353 |
|
| 354 |
Can be used to set a specific random seed |
| 355 |
|
| 356 |
FENNEC_TEST |
| 357 |
|
| 358 |
Can be used to tell Fennec to only run specific tests (can be given a |
| 359 |
line number or a block name). |
| 360 |
|
| 361 |
FENNEC_DEBUG |
| 362 |
|
| 363 |
When true internal debugging is turned on. |
| 364 |
|
| 365 |
EXPORTED FUNCTIONS |
| 366 |
|
| 367 |
FROM FENNEC |
| 368 |
|
| 369 |
done_testing() |
| 370 |
|
| 371 |
done_testing(sub { ... }) |
| 372 |
|
| 373 |
Should be called at the end of your test file to kick off the RSPEC |
| 374 |
tests. Always returns 1, so you can use it as the last statement of |
| 375 |
your module. You must only ever call this once per test file. |
| 376 |
|
| 377 |
Never put tests below the done_testing call. If you want tests to run |
| 378 |
AFTER the RSPEC workflow completes, you can pass done_testing a |
| 379 |
coderef with the tests. |
| 380 |
|
| 381 |
done_testing( sub { |
| 382 |
ok( 1, "This runs after the RSPEC workflow" ); |
| 383 |
}); |
| 384 |
|
| 385 |
FROM Test::Workflow |
| 386 |
|
| 387 |
See Test::Workflow or "EXAMPLES" for more details. |
| 388 |
|
| 389 |
with_tests 'Module::Name'; |
| 390 |
|
| 391 |
Import tests from a module |
| 392 |
|
| 393 |
tests $name => sub { ... }; |
| 394 |
|
| 395 |
tests $name => ( %params ); |
| 396 |
|
| 397 |
it $name => sub { ... }; |
| 398 |
|
| 399 |
it $name => ( %params ); |
| 400 |
|
| 401 |
Define a test block |
| 402 |
|
| 403 |
describe $name => sub { ... }; |
| 404 |
|
| 405 |
Describe a set of tests (group tests and setup/teardown functions) |
| 406 |
|
| 407 |
case $name => sub { ... }; |
| 408 |
|
| 409 |
Used to run a set of tests against multiple conditions |
| 410 |
|
| 411 |
before_all $name => sub { ... }; |
| 412 |
|
| 413 |
Setup, run once before any tests in the describe scope run. |
| 414 |
|
| 415 |
before_case $name => sub { ... }; |
| 416 |
|
| 417 |
Setup, run before any case blocks are run. |
| 418 |
|
| 419 |
before_each $name => sub { ... }; |
| 420 |
|
| 421 |
after_case $name => sub { ... }; |
| 422 |
|
| 423 |
Setup, run once per test, just before it runs. Both run after the |
| 424 |
case block (if there is one). |
| 425 |
|
| 426 |
around_each $name => sub { ... }; |
| 427 |
|
| 428 |
Setup and/or teardown. |
| 429 |
|
| 430 |
after_each $name => sub { ... }; |
| 431 |
|
| 432 |
Teardown, run once per test, after it finishes. |
| 433 |
|
| 434 |
after_all $name => sub { ... }; |
| 435 |
|
| 436 |
Teardown, run once, after all tests in the describe scope complete. |
| 437 |
|
| 438 |
FROM Mock::Quick |
| 439 |
|
| 440 |
See Mock::Quick or "EXAMPLES" for more details. |
| 441 |
|
| 442 |
my $control = qclass $CLASS => ( %PARAMS, %OVERRIDES ); |
| 443 |
|
| 444 |
my $control = qtakeover $CLASS => ( %PARAMS, %OVERRIDES ); |
| 445 |
|
| 446 |
my $control = qimplement $CLASS => ( %PARAMS, %OVERRIDES ); |
| 447 |
|
| 448 |
my $control = qcontrol $CLASS => ( %PARAMS, %OVERRIDES ); |
| 449 |
|
| 450 |
Used to define, takeover, or override parts of other packages. |
| 451 |
|
| 452 |
my $obj = qobj( %PARAMS ); |
| 453 |
|
| 454 |
my ( $obj, $control ) = qobjc( %PARAMS ); |
| 455 |
|
| 456 |
my $obj = qstrict( %PARAMS ); |
| 457 |
|
| 458 |
my ( $obj, $control ) = qstrictc( %PARAMS ); |
| 459 |
|
| 460 |
Define an object specification, quickly. |
| 461 |
|
| 462 |
my $clear = qclear(); |
| 463 |
|
| 464 |
Used to clear a field in a quick object. |
| 465 |
|
| 466 |
my $meth = qmeth { ... }; |
| 467 |
|
| 468 |
my $meth = qmeth( sub { ... } ); |
| 469 |
|
| 470 |
Used to define a method for a quick object. |
| 471 |
|
| 472 |
OTHER |
| 473 |
|
| 474 |
See Test::More, Test::Warn, and Test::Exception |
| 475 |
|
| 476 |
EXAMPLES |
| 477 |
|
| 478 |
Examples can be the best form of documentation. |
| 479 |
|
| 480 |
SIMPLE |
| 481 |
|
| 482 |
VANILLA SYNTAX |
| 483 |
|
| 484 |
t/simple.t |
| 485 |
|
| 486 |
use strict; |
| 487 |
use warnings; |
| 488 |
|
| 489 |
use Fennec; |
| 490 |
|
| 491 |
use_ok 'Data::Dumper'; |
| 492 |
|
| 493 |
tests dumper => sub { |
| 494 |
my $VAR1; |
| 495 |
is_deeply( |
| 496 |
eval Dumper({ a => 1 }), |
| 497 |
{ a => 1 }, |
| 498 |
"Serialize and De-Serialize" |
| 499 |
); |
| 500 |
}; |
| 501 |
|
| 502 |
tests future => ( |
| 503 |
todo => "Not ready yet", |
| 504 |
code => sub { |
| 505 |
ok( 0, "I still have to write these" ); |
| 506 |
}, |
| 507 |
); |
| 508 |
|
| 509 |
done_testing; |
| 510 |
|
| 511 |
DECLARE SYNTAX |
| 512 |
|
| 513 |
t/simple.t |
| 514 |
|
| 515 |
use strict; |
| 516 |
use warnings; |
| 517 |
|
| 518 |
use Fennec::Declare; |
| 519 |
|
| 520 |
use_ok 'Data::Dumper'; |
| 521 |
|
| 522 |
tests dumper { |
| 523 |
my $VAR1; |
| 524 |
is_deeply( |
| 525 |
eval Dumper({ a => 1 }), |
| 526 |
{ a => 1 }, |
| 527 |
"Serialize and De-Serialize" |
| 528 |
); |
| 529 |
|
| 530 |
is( |
| 531 |
eval { no strict; Dumper( { a => 1 } ) }, |
| 532 |
{ a => 1 }, |
| 533 |
"Serialize and De-Serialize" |
| 534 |
); |
| 535 |
} |
| 536 |
|
| 537 |
tests future( todo => "Not ready yet" ) { |
| 538 |
ok( 0, "I still have to write these" ); |
| 539 |
} |
| 540 |
|
| 541 |
done_testing; |
| 542 |
|
| 543 |
RUN TESTS UNDER DIFFERENT CONDITIONS |
| 544 |
|
| 545 |
This example shows 4 conditions ($letter as 'a', 'b', 'c', and 'd'). It |
| 546 |
also has 2 test blocks, one that verifies $letter is a letter, the |
| 547 |
other verifies it is lowercase. Each test block will be run once for |
| 548 |
each condition, 2*4=8, so in total 8 tests will be run. |
| 549 |
|
| 550 |
VANILLA |
| 551 |
|
| 552 |
sample.t: |
| 553 |
|
| 554 |
use strict; |
| 555 |
use warnings; |
| 556 |
|
| 557 |
use Fennec; |
| 558 |
|
| 559 |
my $letter; |
| 560 |
case a => sub { $letter = 'a' }; |
| 561 |
case b => sub { $letter = 'b' }; |
| 562 |
case c => sub { $letter = 'c' }; |
| 563 |
case d => sub { $letter = 'd' }; |
| 564 |
|
| 565 |
tests is_letter => sub { |
| 566 |
like( $letter, qr/^[a-z]$/i, "Got a letter" ); |
| 567 |
}; |
| 568 |
|
| 569 |
tests is_lowercase => sub { |
| 570 |
is( $letter, lc( $letter ), "Letter is lowercase" ); |
| 571 |
}; |
| 572 |
|
| 573 |
done_testing; |
| 574 |
|
| 575 |
OBJECT ORIENTED |
| 576 |
|
| 577 |
sample.t |
| 578 |
|
| 579 |
use strict; |
| 580 |
use warnings; |
| 581 |
|
| 582 |
use Fennec; |
| 583 |
|
| 584 |
sub letter { |
| 585 |
my $self = shift; |
| 586 |
( $self->{letter} ) = @_ if @_; |
| 587 |
return $self->{letter}; |
| 588 |
} |
| 589 |
|
| 590 |
describe letters => sub { |
| 591 |
case a => sub { shift->letter('a') }; |
| 592 |
case b => sub { shift->letter('b') }; |
| 593 |
case c => sub { shift->letter('c') }; |
| 594 |
case d => sub { shift->letter('d') }; |
| 595 |
|
| 596 |
tests is_letter => sub { |
| 597 |
my $self = shift; |
| 598 |
like( $self->letter, qr/^[a-z]$/i, "Got a letter" ); |
| 599 |
}; |
| 600 |
|
| 601 |
tests is_lowercase => sub { |
| 602 |
my $self = shift; |
| 603 |
is( $self->letter, lc( $self->letter ), "Letter is lowercase" ); |
| 604 |
}; |
| 605 |
}; |
| 606 |
|
| 607 |
done_testing; |
| 608 |
|
| 609 |
DECLARE |
| 610 |
|
| 611 |
Note: no need to shift $self, it is done for you! |
| 612 |
|
| 613 |
sample.t |
| 614 |
|
| 615 |
use strict; |
| 616 |
use warnings; |
| 617 |
|
| 618 |
use Fennec::Declare; |
| 619 |
|
| 620 |
sub letter { |
| 621 |
my $self = shift; |
| 622 |
( $self->{letter} ) = @_ if @_; |
| 623 |
return $self->{letter}; |
| 624 |
} |
| 625 |
|
| 626 |
describe letters { |
| 627 |
case a { $self->letter('a') } |
| 628 |
|
| 629 |
case b { $self->letter('b') } |
| 630 |
|
| 631 |
case c { $self->letter('c') } |
| 632 |
|
| 633 |
case d { $self->letter('d') } |
| 634 |
|
| 635 |
tests is_letter { |
| 636 |
like( $self->letter, qr/^[a-z]$/i, "Got a letter" ); |
| 637 |
} |
| 638 |
|
| 639 |
tests is_lowercase { |
| 640 |
is( $self->letter, lc( $self->letter ), "Letter is lowercase" ); |
| 641 |
} |
| 642 |
} |
| 643 |
|
| 644 |
done_testing; |
| 645 |
|
| 646 |
MOCKING |
| 647 |
|
| 648 |
See Mock::Quick for more details |
| 649 |
|
| 650 |
OBJECT ON THE FLY |
| 651 |
|
| 652 |
my $obj = qobj( |
| 653 |
foo => 'foo', |
| 654 |
bar => qmeth { 'bar' }, |
| 655 |
baz => sub { 'baz' }, |
| 656 |
); |
| 657 |
|
| 658 |
is( $obj->foo, 'foo' ); |
| 659 |
is( $obj->bar, 'bar' ); |
| 660 |
is( ref $obj->baz, 'CODE', "baz is a method that returns a coderef" ); |
| 661 |
|
| 662 |
# All methods autovivify as read/write accessors: |
| 663 |
lives_ok { $obj->blah( 'x' ) }; |
| 664 |
|
| 665 |
# use qstrict() to make an object that does not autovivify accessors. |
| 666 |
|
| 667 |
SCOPE OF MOCKS IN FENNEC |
| 668 |
|
| 669 |
With vanilla Mock::Quick a mock is destroyed when the control object is |
| 670 |
destroyed. |
| 671 |
|
| 672 |
my $control = qtakeover Foo => (blah => 'blah'); |
| 673 |
is( Foo->blah, 'blah', "got mock" ); |
| 674 |
$control = undef; |
| 675 |
ok( !Foo->can('blah'), "Mock destroyed" ); |
| 676 |
|
| 677 |
# WITHOUT FENNEC This issues a warning, the $control object is ignored so |
| 678 |
# the mock is destroyed before it can be used. |
| 679 |
qtakover Foo => (blah => 'blah'); |
| 680 |
ok( !Foo->can('blah'), "Mock destroyed before it could be used" ); |
| 681 |
|
| 682 |
With the workflow support provided by Fennec, you can omit the control |
| 683 |
object and let the mock be scoped implicitly. |
| 684 |
|
| 685 |
tests implicit_mock_scope => sub { |
| 686 |
my $self = shift; |
| 687 |
can_ok( $self, 'QINTERCEPT' ); |
| 688 |
qtakeover Foo => (blah => sub { 'blah' }); |
| 689 |
is( Foo->blah, 'blah', "Mock not auto-destroyed" ); |
| 690 |
}; |
| 691 |
|
| 692 |
describe detailed_implicit_mock_scope => sub { |
| 693 |
qtakeover Foo => ( outer => 'outer' ); |
| 694 |
ok( !Foo->can( 'outer' ), "No Leak" ); |
| 695 |
|
| 696 |
before_all ba => sub { |
| 697 |
qtakeover Foo => ( ba => 'ba' ); |
| 698 |
can_ok( 'Foo', qw/outer ba/ ); |
| 699 |
}; |
| 700 |
|
| 701 |
before_each be => sub { |
| 702 |
qtakeover Foo => ( be => 'be' ); |
| 703 |
can_ok( 'Foo', qw/outer ba be/ ); |
| 704 |
}; |
| 705 |
|
| 706 |
tests the_check => sub { |
| 707 |
qtakeover Foo => ( inner => 'inner' ); |
| 708 |
|
| 709 |
can_ok( 'Foo', qw/outer ba be inner/ ); |
| 710 |
}; |
| 711 |
|
| 712 |
ok( !Foo->can( 'outer' ), "No Leak" ); |
| 713 |
ok( !Foo->can( 'ba' ), "No Leak" ); |
| 714 |
ok( !Foo->can( 'be' ), "No Leak" ); |
| 715 |
ok( !Foo->can( 'inner' ), "No Leak" ); |
| 716 |
}; |
| 717 |
|
| 718 |
TAKEOVER AN EXISTING CLASS |
| 719 |
|
| 720 |
require Some::Class; |
| 721 |
my $control = qtakeover 'Some::Class' => ( |
| 722 |
# Override some methods: |
| 723 |
foo => sub { 'foo' }, |
| 724 |
bar => sub { 'bar' }, |
| 725 |
|
| 726 |
# For methods that return a simple value you don't actually need to |
| 727 |
# wrap them in a sub. |
| 728 |
baz => 'bat', |
| 729 |
); |
| 730 |
|
| 731 |
is( Some::Class->foo, 'foo' ); |
| 732 |
is( Some::Class->bar, 'bar' ); |
| 733 |
|
| 734 |
# Use the control object to make another override |
| 735 |
$control->override( foo => 'FOO' ); |
| 736 |
is( Some::Class->foo, 'FOO' ); |
| 737 |
|
| 738 |
# Original class is restored when $control falls out of scope. |
| 739 |
$control = undef; |
| 740 |
|
| 741 |
MOCK A CLASS INSTEAD OF LOADING THE REAL ONE |
| 742 |
|
| 743 |
This will prevent the real class from loading if code tries to require |
| 744 |
or use it. However when the control object falls out of scope you will |
| 745 |
be able to load the real one again. |
| 746 |
|
| 747 |
my $control = qimplement 'Some::Class' => ( |
| 748 |
my_method => sub { ... } |
| 749 |
simple => 'foo', |
| 750 |
); |
| 751 |
|
| 752 |
MOCK AN ANONYMOUS CLASS |
| 753 |
|
| 754 |
my $control = qclass( |
| 755 |
-with_new => 1, # Make a constructor for us |
| 756 |
method => sub { ... }, |
| 757 |
simple => 'foo', |
| 758 |
); |
| 759 |
|
| 760 |
my $obj = $control->package->new; |
| 761 |
|
| 762 |
REUSABLE TEST LIBRARIES |
| 763 |
|
| 764 |
This is a test library that verifies your test file uses strict in the |
| 765 |
first 3 lines. You can also pass with_tests => [ 'Some::Test::Lib' ] as |
| 766 |
an import argument to Fennec. This matters because you can subclass |
| 767 |
Fennec to always include this library. |
| 768 |
|
| 769 |
t/test.t |
| 770 |
|
| 771 |
use strict; |
| 772 |
use warnings; |
| 773 |
use Fennec; |
| 774 |
|
| 775 |
with_tests 'Some::Test::Lib'; |
| 776 |
|
| 777 |
done_testing; |
| 778 |
|
| 779 |
lib/Some/Test/Lib.pm |
| 780 |
|
| 781 |
package Some::Test::Lib; |
| 782 |
use Test::Workflow; |
| 783 |
use Test::More; |
| 784 |
use Scalar::Util qw/blessed/; |
| 785 |
|
| 786 |
tests check_use_strict => sub { |
| 787 |
my $self = shift; |
| 788 |
my $class = blessed $self; |
| 789 |
|
| 790 |
my $file = $class; |
| 791 |
$file =~ s{::}{/}g; |
| 792 |
$file .= '.pm'; |
| 793 |
|
| 794 |
my $full = $INC{$file}; |
| 795 |
ok( -e $full, "Found path and filename for $class" ); |
| 796 |
open( my $fh, '<', $full ) || die $!; |
| 797 |
my $found = 0; |
| 798 |
|
| 799 |
for ( 1 .. 3 ) { |
| 800 |
$found = <$fh> =~ m/^\s*use strict;\s*$/; |
| 801 |
last if $found; |
| 802 |
} |
| 803 |
close($fh); |
| 804 |
ok( $found, "'use strict;' is in the first 3 lines of the test file" ); |
| 805 |
} |
| 806 |
|
| 807 |
1; |
| 808 |
|
| 809 |
POST TESTS |
| 810 |
|
| 811 |
You cannot put any tests under done_testing() Doing so will cause |
| 812 |
problems. However you can put tests IN done_testing. |
| 813 |
|
| 814 |
use strict; |
| 815 |
use warnings; |
| 816 |
|
| 817 |
use Fennec; |
| 818 |
|
| 819 |
my $foo = 1; |
| 820 |
|
| 821 |
is( $foo, 1, "foo is 1" ); |
| 822 |
|
| 823 |
done_testing( |
| 824 |
sub { |
| 825 |
is( $foo, 1, "foo is still 1" ); |
| 826 |
} |
| 827 |
); |
| 828 |
|
| 829 |
RSPEC |
| 830 |
|
| 831 |
The following test will produce output similar to the following. Keep |
| 832 |
in mind that the concurrent nature of Fennec means that the lines for |
| 833 |
each process may appear out of order relative to lines from other |
| 834 |
processes. Lines for any given process will always be in the correct |
| 835 |
order though. |
| 836 |
|
| 837 |
Spacing has been added, and process output has been grouped together, |
| 838 |
except for the main process to demonstrate that after_all really does |
| 839 |
come last. |
| 840 |
|
| 841 |
# PID OUTPUT |
| 842 |
#--------------------------------------------- |
| 843 |
7253 describe runs long before everything else |
| 844 |
7253 before_all runs first |
| 845 |
|
| 846 |
7254 case runs between before_all and before_each |
| 847 |
7254 before_each runs just before tests |
| 848 |
7254 tests run in the middle |
| 849 |
7254 after_each runs just after tests |
| 850 |
|
| 851 |
7255 before_each runs just before tests |
| 852 |
7255 This test inherits the before and after blocks from the parent describe. |
| 853 |
7255 after_each runs just after tests |
| 854 |
|
| 855 |
7253 after_all runs last. |
| 856 |
|
| 857 |
sample.t |
| 858 |
|
| 859 |
use strict; |
| 860 |
use warnings; |
| 861 |
|
| 862 |
use Fennec; |
| 863 |
|
| 864 |
describe order => sub { |
| 865 |
print "$$ describe runs long before everything else\n"; |
| 866 |
|
| 867 |
before_all setup_a => sub { |
| 868 |
print "$$ before_all runs first\n"; |
| 869 |
}; |
| 870 |
|
| 871 |
case a_case => sub { |
| 872 |
print "$$ case runs between before_all and before_each\n"; |
| 873 |
}; |
| 874 |
|
| 875 |
before_each setup_b => sub { |
| 876 |
print "$$ before_each runs just before tests\n"; |
| 877 |
}; |
| 878 |
|
| 879 |
tests a_test => sub { |
| 880 |
print "$$ tests run in the middle\n"; |
| 881 |
}; |
| 882 |
|
| 883 |
after_each teardown_b => sub { |
| 884 |
print "$$ after_each runs just after tests\n"; |
| 885 |
}; |
| 886 |
|
| 887 |
after_all teardown_a => sub { |
| 888 |
print "$$ after_all runs last.\n"; |
| 889 |
}; |
| 890 |
|
| 891 |
describe nested => sub { |
| 892 |
tests b_test => sub { |
| 893 |
print "$$ This test inherits the before/after/case blocks from the parent describe.\n"; |
| 894 |
}; |
| 895 |
}; |
| 896 |
}; |
| 897 |
|
| 898 |
done_testing; |
| 899 |
|
| 900 |
MANUAL |
| 901 |
|
| 902 |
The manual can be found here: Fennec::Manual it is a sort of Nexus for |
| 903 |
documentation, including this document. |
| 904 |
|
| 905 |
VIM INTEGRATION |
| 906 |
|
| 907 |
Insert this into your .vimrc file to bind the F8 key to running the |
| 908 |
test block directly under your cursor. You can be on any line of the |
| 909 |
test block (except in some cases the first or last line. |
| 910 |
|
| 911 |
function! RunFennecLine() |
| 912 |
let cur_line = line(".") |
| 913 |
exe "!FENNEC_TEST='" . cur_line . "' prove -v -I lib %" |
| 914 |
endfunction |
| 915 |
|
| 916 |
" Go to command mode, save the file, run the current test |
| 917 |
:map <F8> <ESC>:w<cr>:call RunFennecLine()<cr> |
| 918 |
:imap <F8> <ESC>:w<cr>:call RunFennecLine()<cr> |
| 919 |
|
| 920 |
RUNNING FENNEC TEST FILES IN PARALLEL |
| 921 |
|
| 922 |
The best option is to use prove with the -j flag. |
| 923 |
|
| 924 |
Note: The following is no longer a recommended practice, it is however |
| 925 |
still supported |
| 926 |
|
| 927 |
You can also create a custom runner using a single .t file to run all |
| 928 |
your Fennec tests. This has caveats though, such as not knowing which |
| 929 |
test file had problems without checking the failure messages. |
| 930 |
|
| 931 |
This will find all *.ft and/or *.pm modules under the t/ directory. It |
| 932 |
will load and run any found. These will be run in parallel |
| 933 |
|
| 934 |
t/runner.t #!/usr/bin/perl use strict; use warnings; |
| 935 |
|
| 936 |
# Paths are optional, if none are specified it defaults to 't/' |
| 937 |
use Fennec::Finder( 't/' ); |
| 938 |
|
| 939 |
# The next lines are optional, if you have no custom configuration to apply |
| 940 |
# you can jump right to 'done_testing'. |
| 941 |
|
| 942 |
# Get the runner (singleton) |
| 943 |
my $runner = Fennec::Finder->new; |
| 944 |
$runner->parallel( 3 ); |
| 945 |
|
| 946 |
# You must call this. |
| 947 |
run(); |
| 948 |
|
| 949 |
AUTHORS |
| 950 |
|
| 951 |
Chad Granum [email protected] |
| 952 |
|
| 953 |
COPYRIGHT |
| 954 |
|
| 955 |
Copyright (C) 2013 Chad Granum |
| 956 |
|
| 957 |
Fennec is free software; Standard perl license (GPL and Artistic). |
| 958 |
|
| 959 |
Fennec is distributed in the hope that it will be useful, but WITHOUT |
| 960 |
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 961 |
FITNESS FOR A PARTICULAR PURPOSE. See the license for more details. |
| 962 |
|