1<a name="#unittest_toolchain"></a> 2## unittest_toolchain 3 4<pre> 5unittest_toolchain(<a href="#unittest_toolchain-name">name</a>, <a href="#unittest_toolchain-failure_templ">failure_templ</a>, <a href="#unittest_toolchain-file_ext">file_ext</a>, <a href="#unittest_toolchain-join_on">join_on</a>, <a href="#unittest_toolchain-success_templ">success_templ</a>) 6</pre> 7 8 9 10### Attributes 11 12<table class="params-table"> 13 <colgroup> 14 <col class="col-param" /> 15 <col class="col-description" /> 16 </colgroup> 17 <tbody> 18 <tr id="unittest_toolchain-name"> 19 <td><code>name</code></td> 20 <td> 21 <a href="https://bazel.build/docs/build-ref.html#name">Name</a>; required 22 <p> 23 A unique name for this target. 24 </p> 25 </td> 26 </tr> 27 <tr id="unittest_toolchain-failure_templ"> 28 <td><code>failure_templ</code></td> 29 <td> 30 String; required 31 </td> 32 </tr> 33 <tr id="unittest_toolchain-file_ext"> 34 <td><code>file_ext</code></td> 35 <td> 36 String; required 37 </td> 38 </tr> 39 <tr id="unittest_toolchain-join_on"> 40 <td><code>join_on</code></td> 41 <td> 42 String; required 43 </td> 44 </tr> 45 <tr id="unittest_toolchain-success_templ"> 46 <td><code>success_templ</code></td> 47 <td> 48 String; required 49 </td> 50 </tr> 51 </tbody> 52</table> 53 54 55## analysistest.make 56 57<pre> 58analysistest.make(<a href="#analysistest.make-impl">impl</a>, <a href="#analysistest.make-expect_failure">expect_failure</a>, <a href="#analysistest.make-attrs">attrs</a>, <a href="#analysistest.make-config_settings">config_settings</a>) 59</pre> 60 61Creates an analysis test rule from its implementation function. 62 63An analysis test verifies the behavior of a "real" rule target by examining 64and asserting on the providers given by the real target. 65 66Each analysis test is defined in an implementation function that must then be 67associated with a rule so that a target can be built. This function handles 68the boilerplate to create and return a test rule and captures the 69implementation function's name so that it can be printed in test feedback. 70 71An example of an analysis test: 72 73``` 74def _your_test(ctx): 75 env = analysistest.begin(ctx) 76 77 # Assert statements go here 78 79 return analysistest.end(env) 80 81your_test = analysistest.make(_your_test) 82``` 83 84Recall that names of test rules must end in `_test`. 85 86 87### Parameters 88 89<table class="params-table"> 90 <colgroup> 91 <col class="col-param" /> 92 <col class="col-description" /> 93 </colgroup> 94 <tbody> 95 <tr id="analysistest.make-impl"> 96 <td><code>impl</code></td> 97 <td> 98 required. 99 <p> 100 The implementation function of the unit test. 101 </p> 102 </td> 103 </tr> 104 <tr id="analysistest.make-expect_failure"> 105 <td><code>expect_failure</code></td> 106 <td> 107 optional. default is <code>False</code> 108 <p> 109 If true, the analysis test will expect the target_under_test 110 to fail. Assertions can be made on the underlying failure using asserts.expect_failure 111 </p> 112 </td> 113 </tr> 114 <tr id="analysistest.make-attrs"> 115 <td><code>attrs</code></td> 116 <td> 117 optional. default is <code>{}</code> 118 <p> 119 An optional dictionary to supplement the attrs passed to the 120 unit test's `rule()` constructor. 121 </p> 122 </td> 123 </tr> 124 <tr id="analysistest.make-config_settings"> 125 <td><code>config_settings</code></td> 126 <td> 127 optional. default is <code>{}</code> 128 <p> 129 A dictionary of configuration settings to change for the target under 130 test and its dependencies. This may be used to essentially change 'build flags' for 131 the target under test, and may thus be utilized to test multiple targets with different 132 flags in a single build 133 </p> 134 </td> 135 </tr> 136 </tbody> 137</table> 138 139 140## analysistest.begin 141 142<pre> 143analysistest.begin(<a href="#analysistest.begin-ctx">ctx</a>) 144</pre> 145 146Begins a unit test. 147 148This should be the first function called in a unit test implementation 149function. It initializes a "test environment" that is used to collect 150assertion failures so that they can be reported and logged at the end of the 151test. 152 153 154### Parameters 155 156<table class="params-table"> 157 <colgroup> 158 <col class="col-param" /> 159 <col class="col-description" /> 160 </colgroup> 161 <tbody> 162 <tr id="analysistest.begin-ctx"> 163 <td><code>ctx</code></td> 164 <td> 165 required. 166 <p> 167 The Skylark context. Pass the implementation function's `ctx` argument 168 in verbatim. 169 </p> 170 </td> 171 </tr> 172 </tbody> 173</table> 174 175 176## analysistest.end 177 178<pre> 179analysistest.end(<a href="#analysistest.end-env">env</a>) 180</pre> 181 182Ends an analysis test and logs the results. 183 184This must be called and returned at the end of an analysis test implementation function so 185that the results are reported. 186 187 188### Parameters 189 190<table class="params-table"> 191 <colgroup> 192 <col class="col-param" /> 193 <col class="col-description" /> 194 </colgroup> 195 <tbody> 196 <tr id="analysistest.end-env"> 197 <td><code>env</code></td> 198 <td> 199 required. 200 <p> 201 The test environment returned by `analysistest.begin`. 202 </p> 203 </td> 204 </tr> 205 </tbody> 206</table> 207 208 209## analysistest.fail 210 211<pre> 212analysistest.fail(<a href="#analysistest.fail-env">env</a>, <a href="#analysistest.fail-msg">msg</a>) 213</pre> 214 215Unconditionally causes the current test to fail. 216 217### Parameters 218 219<table class="params-table"> 220 <colgroup> 221 <col class="col-param" /> 222 <col class="col-description" /> 223 </colgroup> 224 <tbody> 225 <tr id="analysistest.fail-env"> 226 <td><code>env</code></td> 227 <td> 228 required. 229 <p> 230 The test environment returned by `unittest.begin`. 231 </p> 232 </td> 233 </tr> 234 <tr id="analysistest.fail-msg"> 235 <td><code>msg</code></td> 236 <td> 237 required. 238 <p> 239 The message to log describing the failure. 240 </p> 241 </td> 242 </tr> 243 </tbody> 244</table> 245 246 247## analysistest.target_actions 248 249<pre> 250analysistest.target_actions(<a href="#analysistest.target_actions-env">env</a>) 251</pre> 252 253Returns a list of actions registered by the target under test. 254 255### Parameters 256 257<table class="params-table"> 258 <colgroup> 259 <col class="col-param" /> 260 <col class="col-description" /> 261 </colgroup> 262 <tbody> 263 <tr id="analysistest.target_actions-env"> 264 <td><code>env</code></td> 265 <td> 266 required. 267 <p> 268 The test environment returned by `analysistest.begin`. 269 </p> 270 </td> 271 </tr> 272 </tbody> 273</table> 274 275 276## analysistest.target_under_test 277 278<pre> 279analysistest.target_under_test(<a href="#analysistest.target_under_test-env">env</a>) 280</pre> 281 282Returns the target under test. 283 284### Parameters 285 286<table class="params-table"> 287 <colgroup> 288 <col class="col-param" /> 289 <col class="col-description" /> 290 </colgroup> 291 <tbody> 292 <tr id="analysistest.target_under_test-env"> 293 <td><code>env</code></td> 294 <td> 295 required. 296 <p> 297 The test environment returned by `analysistest.begin`. 298 </p> 299 </td> 300 </tr> 301 </tbody> 302</table> 303 304 305## asserts.expect_failure 306 307<pre> 308asserts.expect_failure(<a href="#asserts.expect_failure-env">env</a>, <a href="#asserts.expect_failure-expected_failure_msg">expected_failure_msg</a>) 309</pre> 310 311Asserts that the target under test has failed with a given error message. 312 313This requires that the analysis test is created with `analysistest.make()` and 314`expect_failures = True` is specified. 315 316 317### Parameters 318 319<table class="params-table"> 320 <colgroup> 321 <col class="col-param" /> 322 <col class="col-description" /> 323 </colgroup> 324 <tbody> 325 <tr id="asserts.expect_failure-env"> 326 <td><code>env</code></td> 327 <td> 328 required. 329 <p> 330 The test environment returned by `analysistest.begin`. 331 </p> 332 </td> 333 </tr> 334 <tr id="asserts.expect_failure-expected_failure_msg"> 335 <td><code>expected_failure_msg</code></td> 336 <td> 337 optional. default is <code>""</code> 338 <p> 339 The error message to expect as a result of analysis failures. 340 </p> 341 </td> 342 </tr> 343 </tbody> 344</table> 345 346 347## asserts.equals 348 349<pre> 350asserts.equals(<a href="#asserts.equals-env">env</a>, <a href="#asserts.equals-expected">expected</a>, <a href="#asserts.equals-actual">actual</a>, <a href="#asserts.equals-msg">msg</a>) 351</pre> 352 353Asserts that the given `expected` and `actual` values are equal. 354 355### Parameters 356 357<table class="params-table"> 358 <colgroup> 359 <col class="col-param" /> 360 <col class="col-description" /> 361 </colgroup> 362 <tbody> 363 <tr id="asserts.equals-env"> 364 <td><code>env</code></td> 365 <td> 366 required. 367 <p> 368 The test environment returned by `unittest.begin`. 369 </p> 370 </td> 371 </tr> 372 <tr id="asserts.equals-expected"> 373 <td><code>expected</code></td> 374 <td> 375 required. 376 <p> 377 The expected value of some computation. 378 </p> 379 </td> 380 </tr> 381 <tr id="asserts.equals-actual"> 382 <td><code>actual</code></td> 383 <td> 384 required. 385 <p> 386 The actual value returned by some computation. 387 </p> 388 </td> 389 </tr> 390 <tr id="asserts.equals-msg"> 391 <td><code>msg</code></td> 392 <td> 393 optional. default is <code>None</code> 394 <p> 395 An optional message that will be printed that describes the failure. 396 If omitted, a default will be used. 397 </p> 398 </td> 399 </tr> 400 </tbody> 401</table> 402 403 404## asserts.false 405 406<pre> 407asserts.false(<a href="#asserts.false-env">env</a>, <a href="#asserts.false-condition">condition</a>, <a href="#asserts.false-msg">msg</a>) 408</pre> 409 410Asserts that the given `condition` is false. 411 412### Parameters 413 414<table class="params-table"> 415 <colgroup> 416 <col class="col-param" /> 417 <col class="col-description" /> 418 </colgroup> 419 <tbody> 420 <tr id="asserts.false-env"> 421 <td><code>env</code></td> 422 <td> 423 required. 424 <p> 425 The test environment returned by `unittest.begin`. 426 </p> 427 </td> 428 </tr> 429 <tr id="asserts.false-condition"> 430 <td><code>condition</code></td> 431 <td> 432 required. 433 <p> 434 A value that will be evaluated in a Boolean context. 435 </p> 436 </td> 437 </tr> 438 <tr id="asserts.false-msg"> 439 <td><code>msg</code></td> 440 <td> 441 optional. default is <code>"Expected condition to be false, but was true."</code> 442 <p> 443 An optional message that will be printed that describes the failure. 444 If omitted, a default will be used. 445 </p> 446 </td> 447 </tr> 448 </tbody> 449</table> 450 451 452## asserts.set_equals 453 454<pre> 455asserts.set_equals(<a href="#asserts.set_equals-env">env</a>, <a href="#asserts.set_equals-expected">expected</a>, <a href="#asserts.set_equals-actual">actual</a>, <a href="#asserts.set_equals-msg">msg</a>) 456</pre> 457 458Asserts that the given `expected` and `actual` sets are equal. 459 460### Parameters 461 462<table class="params-table"> 463 <colgroup> 464 <col class="col-param" /> 465 <col class="col-description" /> 466 </colgroup> 467 <tbody> 468 <tr id="asserts.set_equals-env"> 469 <td><code>env</code></td> 470 <td> 471 required. 472 <p> 473 The test environment returned by `unittest.begin`. 474 </p> 475 </td> 476 </tr> 477 <tr id="asserts.set_equals-expected"> 478 <td><code>expected</code></td> 479 <td> 480 required. 481 <p> 482 The expected set resulting from some computation. 483 </p> 484 </td> 485 </tr> 486 <tr id="asserts.set_equals-actual"> 487 <td><code>actual</code></td> 488 <td> 489 required. 490 <p> 491 The actual set returned by some computation. 492 </p> 493 </td> 494 </tr> 495 <tr id="asserts.set_equals-msg"> 496 <td><code>msg</code></td> 497 <td> 498 optional. default is <code>None</code> 499 <p> 500 An optional message that will be printed that describes the failure. 501 If omitted, a default will be used. 502 </p> 503 </td> 504 </tr> 505 </tbody> 506</table> 507 508 509## asserts.new_set_equals 510 511<pre> 512asserts.new_set_equals(<a href="#asserts.new_set_equals-env">env</a>, <a href="#asserts.new_set_equals-expected">expected</a>, <a href="#asserts.new_set_equals-actual">actual</a>, <a href="#asserts.new_set_equals-msg">msg</a>) 513</pre> 514 515Asserts that the given `expected` and `actual` sets are equal. 516 517### Parameters 518 519<table class="params-table"> 520 <colgroup> 521 <col class="col-param" /> 522 <col class="col-description" /> 523 </colgroup> 524 <tbody> 525 <tr id="asserts.new_set_equals-env"> 526 <td><code>env</code></td> 527 <td> 528 required. 529 <p> 530 The test environment returned by `unittest.begin`. 531 </p> 532 </td> 533 </tr> 534 <tr id="asserts.new_set_equals-expected"> 535 <td><code>expected</code></td> 536 <td> 537 required. 538 <p> 539 The expected set resulting from some computation. 540 </p> 541 </td> 542 </tr> 543 <tr id="asserts.new_set_equals-actual"> 544 <td><code>actual</code></td> 545 <td> 546 required. 547 <p> 548 The actual set returned by some computation. 549 </p> 550 </td> 551 </tr> 552 <tr id="asserts.new_set_equals-msg"> 553 <td><code>msg</code></td> 554 <td> 555 optional. default is <code>None</code> 556 <p> 557 An optional message that will be printed that describes the failure. 558 If omitted, a default will be used. 559 </p> 560 </td> 561 </tr> 562 </tbody> 563</table> 564 565 566## asserts.true 567 568<pre> 569asserts.true(<a href="#asserts.true-env">env</a>, <a href="#asserts.true-condition">condition</a>, <a href="#asserts.true-msg">msg</a>) 570</pre> 571 572Asserts that the given `condition` is true. 573 574### Parameters 575 576<table class="params-table"> 577 <colgroup> 578 <col class="col-param" /> 579 <col class="col-description" /> 580 </colgroup> 581 <tbody> 582 <tr id="asserts.true-env"> 583 <td><code>env</code></td> 584 <td> 585 required. 586 <p> 587 The test environment returned by `unittest.begin`. 588 </p> 589 </td> 590 </tr> 591 <tr id="asserts.true-condition"> 592 <td><code>condition</code></td> 593 <td> 594 required. 595 <p> 596 A value that will be evaluated in a Boolean context. 597 </p> 598 </td> 599 </tr> 600 <tr id="asserts.true-msg"> 601 <td><code>msg</code></td> 602 <td> 603 optional. default is <code>"Expected condition to be true, but was false."</code> 604 <p> 605 An optional message that will be printed that describes the failure. 606 If omitted, a default will be used. 607 </p> 608 </td> 609 </tr> 610 </tbody> 611</table> 612 613 614## register_unittest_toolchains 615 616<pre> 617register_unittest_toolchains() 618</pre> 619 620Registers the toolchains for unittest users. 621 622 623 624## unittest.make 625 626<pre> 627unittest.make(<a href="#unittest.make-impl">impl</a>, <a href="#unittest.make-attrs">attrs</a>) 628</pre> 629 630Creates a unit test rule from its implementation function. 631 632Each unit test is defined in an implementation function that must then be 633associated with a rule so that a target can be built. This function handles 634the boilerplate to create and return a test rule and captures the 635implementation function's name so that it can be printed in test feedback. 636 637The optional `attrs` argument can be used to define dependencies for this 638test, in order to form unit tests of rules. 639 640An example of a unit test: 641 642``` 643def _your_test(ctx): 644 env = unittest.begin(ctx) 645 646 # Assert statements go here 647 648 return unittest.end(env) 649 650your_test = unittest.make(_your_test) 651``` 652 653Recall that names of test rules must end in `_test`. 654 655 656### Parameters 657 658<table class="params-table"> 659 <colgroup> 660 <col class="col-param" /> 661 <col class="col-description" /> 662 </colgroup> 663 <tbody> 664 <tr id="unittest.make-impl"> 665 <td><code>impl</code></td> 666 <td> 667 required. 668 <p> 669 The implementation function of the unit test. 670 </p> 671 </td> 672 </tr> 673 <tr id="unittest.make-attrs"> 674 <td><code>attrs</code></td> 675 <td> 676 optional. default is <code>{}</code> 677 <p> 678 An optional dictionary to supplement the attrs passed to the 679 unit test's `rule()` constructor. 680 </p> 681 </td> 682 </tr> 683 </tbody> 684</table> 685 686 687## unittest.suite 688 689<pre> 690unittest.suite(<a href="#unittest.suite-name">name</a>, <a href="#unittest.suite-test_rules">test_rules</a>) 691</pre> 692 693Defines a `test_suite` target that contains multiple tests. 694 695After defining your test rules in a `.bzl` file, you need to create targets 696from those rules so that `blaze test` can execute them. Doing this manually 697in a BUILD file would consist of listing each test in your `load` statement 698and then creating each target one by one. To reduce duplication, we recommend 699writing a macro in your `.bzl` file to instantiate all targets, and calling 700that macro from your BUILD file so you only have to load one symbol. 701 702For the case where your unit tests do not take any (non-default) attributes -- 703i.e., if your unit tests do not test rules -- you can use this function to 704create the targets and wrap them in a single test_suite target. In your 705`.bzl` file, write: 706 707``` 708def your_test_suite(): 709 unittest.suite( 710 "your_test_suite", 711 your_test, 712 your_other_test, 713 yet_another_test, 714 ) 715``` 716 717Then, in your `BUILD` file, simply load the macro and invoke it to have all 718of the targets created: 719 720``` 721load("//path/to/your/package:tests.bzl", "your_test_suite") 722your_test_suite() 723``` 724 725If you pass _N_ unit test rules to `unittest.suite`, _N_ + 1 targets will be 726created: a `test_suite` target named `${name}` (where `${name}` is the name 727argument passed in here) and targets named `${name}_test_${i}`, where `${i}` 728is the index of the test in the `test_rules` list, which is used to uniquely 729name each target. 730 731 732### Parameters 733 734<table class="params-table"> 735 <colgroup> 736 <col class="col-param" /> 737 <col class="col-description" /> 738 </colgroup> 739 <tbody> 740 <tr id="unittest.suite-name"> 741 <td><code>name</code></td> 742 <td> 743 required. 744 <p> 745 The name of the `test_suite` target, and the prefix of all the test 746 target names. 747 </p> 748 </td> 749 </tr> 750 <tr id="unittest.suite-test_rules"> 751 <td><code>test_rules</code></td> 752 <td> 753 optional. 754 <p> 755 A list of test rules defines by `unittest.test`. 756 </p> 757 </td> 758 </tr> 759 </tbody> 760</table> 761 762 763## unittest.begin 764 765<pre> 766unittest.begin(<a href="#unittest.begin-ctx">ctx</a>) 767</pre> 768 769Begins a unit test. 770 771This should be the first function called in a unit test implementation 772function. It initializes a "test environment" that is used to collect 773assertion failures so that they can be reported and logged at the end of the 774test. 775 776 777### Parameters 778 779<table class="params-table"> 780 <colgroup> 781 <col class="col-param" /> 782 <col class="col-description" /> 783 </colgroup> 784 <tbody> 785 <tr id="unittest.begin-ctx"> 786 <td><code>ctx</code></td> 787 <td> 788 required. 789 <p> 790 The Skylark context. Pass the implementation function's `ctx` argument 791 in verbatim. 792 </p> 793 </td> 794 </tr> 795 </tbody> 796</table> 797 798 799## unittest.end 800 801<pre> 802unittest.end(<a href="#unittest.end-env">env</a>) 803</pre> 804 805Ends a unit test and logs the results. 806 807This must be called and returned at the end of a unit test implementation function so 808that the results are reported. 809 810 811### Parameters 812 813<table class="params-table"> 814 <colgroup> 815 <col class="col-param" /> 816 <col class="col-description" /> 817 </colgroup> 818 <tbody> 819 <tr id="unittest.end-env"> 820 <td><code>env</code></td> 821 <td> 822 required. 823 <p> 824 The test environment returned by `unittest.begin`. 825 </p> 826 </td> 827 </tr> 828 </tbody> 829</table> 830 831 832## unittest.fail 833 834<pre> 835unittest.fail(<a href="#unittest.fail-env">env</a>, <a href="#unittest.fail-msg">msg</a>) 836</pre> 837 838Unconditionally causes the current test to fail. 839 840### Parameters 841 842<table class="params-table"> 843 <colgroup> 844 <col class="col-param" /> 845 <col class="col-description" /> 846 </colgroup> 847 <tbody> 848 <tr id="unittest.fail-env"> 849 <td><code>env</code></td> 850 <td> 851 required. 852 <p> 853 The test environment returned by `unittest.begin`. 854 </p> 855 </td> 856 </tr> 857 <tr id="unittest.fail-msg"> 858 <td><code>msg</code></td> 859 <td> 860 required. 861 <p> 862 The message to log describing the failure. 863 </p> 864 </td> 865 </tr> 866 </tbody> 867</table> 868 869 870