git.llucax.com Git - personal/website.git/blob - source/proj/mutest/manual.html

352 (just write your <a class="reference internal" href="#test-case">test cases</a> grouped in <a class="reference internal" href="#test-suite">test suites</a> and you're

353 set) and so small and simple that you don't mind to copy the files to

354 your project and just use it (i.e., no dependencies).

355 The idea is simple: a source file is a <a class="reference internal" href="#test-suite">test suite</a>, a function is

356 a <a class="reference internal" href="#test-case">test case</a> (special functions can be used for <a class="reference internal" href="#test-suite">test suite</a>

357 <a class="reference internal" href="#initialization">initialization</a> and <a class="reference internal" href="#termination">termination</a>), which can can have several <a class="reference internal" href="#checks">checks</a>.

358 <a class="reference internal" href="#checks">Checks</a> comes in 2 flavors, one that only prints an error, and one that

359 terminates the current <a class="reference internal" href="#test-case">test case</a> too. A (normally) automated <a class="reference internal" href="#test-program">test

360 program</a> run all the <a class="reference internal" href="#test-suite">test suites</a> and print some stats. It fails

361 (returns non-zero) if any <a class="reference internal" href="#test-suite">test suite</a> fails.

362 <div style="width: 220px; height: 270px; float: right; margin-left: 1em; margin-top: 1em">

363 <iframe width="220" height="270" style="border: none; outline: none" src="http://tools.flattr.net/widgets/thing.html?thing=1141711"></iframe>

364 </div>

365 </div>

366 <div class="contents topic" id="contents">

367 Contents

368 <ul class="auto-toc simple">

369 <li><a class="reference internal" href="#installation" id="id9">1.   Installation</a></li>

370 <li><a class="reference internal" href="#quick-sample" id="id10">2.   Quick Sample</a><ul class="auto-toc">

371 <li><a class="reference internal" href="#factorial-c" id="id11">2.1.   factorial.c</a></li>

372 <li><a class="reference internal" href="#factorial-test-c" id="id12">2.2.   factorial_test.c</a></li>

373 <li><a class="reference internal" href="#exception-test-cpp" id="id13">2.3.   exception_test.cpp</a></li>

374 </ul>

375 </li>

376 <li><a class="reference internal" href="#concepts" id="id14">3.   Concepts</a><ul class="auto-toc">

377 <li><a class="reference internal" href="#test-program" id="id15">3.1.   Test Program</a></li>

378 <li><a class="reference internal" href="#test-suite" id="id16">3.2.   Test Suite</a></li>

379 <li><a class="reference internal" href="#test-case" id="id17">3.3.   Test Case</a></li>

380 <li><a class="reference internal" href="#checks" id="id18">3.4.   Checks</a></li>

381 <li><a class="reference internal" href="#initialization" id="id19">3.5.   Initialization</a></li>

382 <li><a class="reference internal" href="#termination" id="id20">3.6.   Termination</a></li>

383 </ul>

384 </li>

385 <li><a class="reference internal" href="#c-support" id="id21">4.   C++ Support</a></li>

386 <li><a class="reference internal" href="#implementations" id="id22">5.   Implementations</a><ul class="auto-toc">

387 <li><a class="reference internal" href="#static-implementations" id="id23">5.1.   Static Implementations</a><ul class="auto-toc">

388 <li><a class="reference internal" href="#c-implementation" id="id24">5.1.1.   C implementation</a><ul class="auto-toc">

389 <li><a class="reference internal" href="#mkmutest-invocation" id="id25">5.1.1.1.   <tt class="docutils literal">mkmutest</tt> Invocation</a></li>

390 <li><a class="reference internal" href="#test-program-invocation" id="id26">5.1.1.2.   Test Program Invocation</a></li>

391 <li><a class="reference internal" href="#dependencies" id="id27">5.1.1.3.   Dependencies</a></li>

392 </ul>

393 </li>

394 </ul>

395 </li>

396 <li><a class="reference internal" href="#dynamic-implementations" id="id28">5.2.   Dynamic Implementations</a><ul class="auto-toc">

397 <li><a class="reference internal" href="#python-implementation" id="id29">5.2.1.   Python implementation</a><ul class="auto-toc">

398 <li><a class="reference internal" href="#mutest-invocation" id="id30">5.2.1.1.   <tt class="docutils literal">mutest</tt> Invocation</a></li>

399 <li><a class="reference internal" href="#id8" id="id31">5.2.1.2.   Dependencies</a></li>

400 </ul>

401 </li>

402 </ul>

403 </li>

404 </ul>

405 </li>

406 <li><a class="reference internal" href="#reference" id="id32">6.   Reference</a><ul class="auto-toc">

407 <li><a class="reference internal" href="#mu-check" id="id33">6.1.   <tt class="docutils literal">mu_check()</tt></a></li>

408 <li><a class="reference internal" href="#mu-ensure" id="id34">6.2.   <tt class="docutils literal">mu_ensure()</tt></a></li>

409 <li><a class="reference internal" href="#mu-echeck" id="id35">6.3.   <tt class="docutils literal">mu_echeck()</tt></a></li>

410 <li><a class="reference internal" href="#mu-eensure" id="id36">6.4.   <tt class="docutils literal">mu_eensure()</tt></a></li>

411 </ul>

412 </li>

413 <li><a class="reference internal" href="#about" id="id37">7.   About</a></li>

414 </ul>

415 </div>

416 <div class="section" id="installation">

417 <h1><a class="toc-backref" href="#id9">1.   Installation</a></h1>

418 Download the <a class="reference external" href="http://proj.llucax.com.ar/home/mutest/releases/mutest.tar.gz">latest distribution tarball</a> and uncompress it.

419 You can also download any release from the <a class="reference external" href="http://proj.llucax.com.ar/home/mutest/releases/">releases directory</a> or get it

420 using <a class="reference external" href="http://git.or.cz/">Git</a> directly from the <a class="reference external" href="http://git.llucax.com.ar/w/software/mutest.git">Git repository</a>.

421 You can get <a class="reference external" href="http://proj.llucax.com.ar/home/mutest/manual.html">this manual</a> too, or a <a class="reference external" href="http://proj.llucax.com.ar/home/mutest/manual.pdf">PDF version</a> of it.

422 To actually install mutest run:

423 <pre class="literal-block">

424 $ make install

425 </pre>

426 Default installation path is <tt class="docutils literal">/usr/local</tt> (because of that, you'll probably

427 need superuser privileges to install to the default location). You can override

428 that by passing the <tt class="docutils literal">prefix</tt> make variable, for example:

429 <pre class="literal-block">

430 $ make prefix=/opt/mutest install

431 </pre>

432 If you want to install just the docs, you can do:

433 <pre class="literal-block">

434 $ make install-doc

435 </pre>

436 Or even <tt class="docutils literal">install-readme</tt>, <tt class="docutils literal">install-html</tt> or <tt class="docutils literal">install-pdf</tt> if you are too

437 picky.

438 If you want to install just one particular <a class="reference internal" href="#implementations">implementation</a>, to can use the

439 <tt class="docutils literal">install-c</tt> and <tt class="docutils literal">install-py</tt> targets.

440 </div>

441 <div class="section" id="quick-sample">

442 <h1><a class="toc-backref" href="#id10">2.   Quick Sample</a></h1>

443 You can find some samples in the <a class="reference external" href="http://git.llucax.com.ar/w/software/mutest.git?a=tree;f=sample;h=d8ad4dd9c3428fef5963107c82ab6a5e34ec6e00;hb=HEAD">sample</a> directory.

444 This is an example taken from there. A simple module called <a class="reference internal" href="#factorial-c">factorial.c</a>

445 with its corresponding <a class="reference internal" href="#test-suite">test suite</a> (<a class="reference internal" href="#factorial-test-c">factorial_test.c</a>).

446 You can see some <a class="reference internal" href="#c-support">C++ support</a> in the <a class="reference internal" href="#exception-test-cpp">exception_test.cpp</a> <a class="reference internal" href="#test-suite">test suite</a>.

447 <div class="section" id="factorial-c">

448 <h2><a class="toc-backref" href="#id11">2.1.   factorial.c</a></h2>

449 <pre class="code c literal-block">

450 /*

451 * This file is part of mutest, a simple micro unit testing framework for C.

452 *

453 * mutest was written by Leandro Lucarella <llucax@gmail.com> and is released

454 * under the BOLA license, please see the LICENSE file or visit:

455 * http://blitiri.com.ar/p/bola/

456 *

457 * This is an example module that calculates a factorial.

458 *

459 * Please, read the README file for more details.

460 */

461

462 unsigned factorial(unsigned x) {

463 if (x <= 1)

464 return 1;

465 return x * factorial(x-1);

466 }

467 </pre>

468 </div>

469 <div class="section" id="factorial-test-c">

470 <h2><a class="toc-backref" href="#id12">2.2.   factorial_test.c</a></h2>

471 <pre class="code c literal-block">

472 /*

473 * This file is part of mutest, a simple micro unit testing framework for C.

474 *

475 * mutest was written by Leandro Lucarella <llucax@gmail.com> and is released

476 * under the BOLA license, please see the LICENSE file or visit:

477 * http://blitiri.com.ar/p/bola/

478 *

479 * This is the factorial module test suite. Each (public) function starting

480 * with mu_test will be picked up by mkmutest as a test case.

481 *

482 * Please, read the README file for more details.

483 */

484

485 #include "factorial.h"

486

487 #include "../mutest.h"

488

489 void mu_test_factorial_zero() {

490 unsigned x = factorial(0);

491 mu_check(x == 1);

492 }

493

494 void mu_test_factorial_one() {

495 unsigned x = factorial(1);

496 /* this test is wrong on purpose, to see how it fails */

497 mu_check(x == 2);

498 }

499

500 void mu_test_factorial_positive() {

501 unsigned x = factorial(2);

502 /* this test is wrong on purpose, to see how it fails */

503 mu_check(x == 3);

504

505 x = factorial(3);

506 /* we don't want to continue if this fails, because the next result

507 * depends on this one. This one will succeed. */

508 mu_ensure(x == 6);

509

510 x = factorial(x);

511 mu_check(x == 720);

512

513 x = factorial(4);

514 mu_ensure(x == 6); /* same as before, but this one will fail. */

515

516 x = factorial(x-15); /* and this will never be executed */

517 mu_check(x == 362881); /* but if excecuted, will fail */

518 }

519 </pre>

520 </div>

521 <div class="section" id="exception-test-cpp">

522 <h2><a class="toc-backref" href="#id13">2.3.   exception_test.cpp</a></h2>

523 <pre class="code c++ literal-block">

524 /*

525 * This file is part of mutest, a simple micro unit testing framework for C.

526 *

527 * mutest was written by Leandro Lucarella <llucax@gmail.com> and is released

528 * under the BOLA license, please see the LICENSE file or visit:

529 * http://blitiri.com.ar/p/bola/

530 *

531 * This is a C++ module test suite. It shows how to use checks involving

532 * exceptions.

533 *

534 * Please, read the README file for more details.

535 */

536

537 #include <stdexcept> // std::out_of_range

538 #include <vector> // std::vector

539

540 #include "../mutest.h"

541

542 extern "C" {

543

544 void mu_test_exceptions() {

545 std::vector<int> v(1);

546 // ok

547 mu_check(v.at(0) == 0);

548 // throws! This fails

549 mu_check(v.at(1) == 0);

550 // ok, we expect the exception to be thrown, and it does

551 mu_echeck(std::out_of_range, v.at(1));

552 // fails! We expect this to throw, but it doesn't

553 mu_echeck(std::out_of_range, v.at(0));

554 // fails again, but this time the show is over (note the "ensure")

555 mu_eensure(std::out_of_range, v.at(0));

556 // this will never be executed (it should fail if it is)

557 mu_check(v.empty());

558 }

559

560 } // extern "C"

561 </pre>

562 </div>

563 </div>

564 <div class="section" id="concepts">

565 <h1><a class="toc-backref" href="#id14">3.   Concepts</a></h1>

566 mutest is about 4 simple concepts: <a class="reference internal" href="#test-program">test program</a>, <a class="reference internal" href="#test-suite">test suite</a>, <a class="reference internal" href="#test-case">test

567 case</a> and <a class="reference internal" href="#checks">checks</a>. Well, to be honest you probably will need <a class="reference internal" href="#test-suite">test suite</a>

568 <a class="reference internal" href="#initialization">initialization</a> and <a class="reference internal" href="#termination">termination</a> too =)

569 <div class="section" id="test-program">

570 <h2><a class="toc-backref" href="#id15">3.1.   Test Program</a></h2>

571 A test program is the higher level unit of mutest. The test program is

572 the one in charge of running all your tests. Probably one of the more important

573 features of mutest is that you are not supposed to bother about the test

574 program. So, different <a class="reference internal" href="#implementations">implementations</a> have different ways to tackle this.

575 Some need more or less interactions from your part, and each have their pros

576 and cons.

577 But this is all you need to know for now, for more details see how the test

578 program is implemented by your <a class="reference internal" href="#implementations">implementation</a> of choice.

579 </div>

580 <div class="section" id="test-suite">

581 <h2><a class="toc-backref" href="#id16">3.2.   Test Suite</a></h2>

582 A test suite is the higher level unit of mutest that you should

583 care about =). Is not much more than a way to group <a class="reference internal" href="#test-case">test cases</a>. Code-wise,

584 a test suite is a C (or C++) module (or compilation unit). Not clear enough?

585 A unit test is an object file (could be a shared object depending on the

586 <a class="reference internal" href="#implementations">implementation</a>). This module should have one or more <a class="reference internal" href="#test-case">test cases</a> and it

587 could have any number (including zero) of <a class="reference internal" href="#initialization">initialization</a> and <a class="reference internal" href="#termination">termination</a>

588 functions.

589 A test suite, is inspected by the <a class="reference internal" href="#test-program">test program</a> for <a class="reference internal" href="#test-case">test cases</a> and

590 <a class="reference internal" href="#initialization">initialization</a> and <a class="reference internal" href="#termination">termination</a> functions, and run them.

591 A test suite fail if one or more <a class="reference internal" href="#test-case">test cases</a> fail, and it's skipped if one or

592 more <a class="reference internal" href="#initialization">initialization</a> functions fail (or, depending on the implementation, if

593 the test suite can't be loaded at all).

594 </div>

595 <div class="section" id="test-case">

596 <h2><a class="toc-backref" href="#id17">3.3.   Test Case</a></h2>

597 A test case is just a plain function with a special signature and name.

598 A test case function name must start with <tt class="docutils literal">mu_test</tt>, and take no arguments

599 and return nothing. For example:

600 <pre class="literal-block">

601 void mu_test_something(void);

602 </pre>

603 A test case (probably) only make sense if it has <a class="reference internal" href="#checks">checks</a>. A test case succeed

604 only if all its checks succeed too.

605 Test are executed in an <a class="reference internal" href="#implementations">implementation</a>-dependant order, but usually the

606 default order is alphabetical.

607 </div>

608 <div class="section" id="checks">

609 <h2><a class="toc-backref" href="#id18">3.4.   Checks</a></h2>

610 Checks are assertions that a <a class="reference internal" href="#test-case">test case</a> must pass (a boolean expression that

611 must evaluate to true). There are 2 big flavors of checks: check and

612 ensure. check just print an error (and mark the <a class="reference internal" href="#test-case">test case</a> as

613 failed) and ensure halt the <a class="reference internal" href="#test-case">test case</a> execution, jumping to the next

614 one.

615 For better <a class="reference internal" href="#c-support">C++ support</a> there are check macros that assert that a specified

616 exception is thrown (instead of check for a boolean expression to evaluate to

617 true).

618 You can take a look at the <a class="reference internal" href="#reference">reference</a> to see the different flavors of check

619 macros in more detail.

620 </div>

621 <div class="section" id="initialization">

622 <h2><a class="toc-backref" href="#id19">3.5.   Initialization</a></h2>

623 Sometimes you need to setup some environment shared between all the <a class="reference internal" href="#test-case">test

624 cases</a> in a <a class="reference internal" href="#test-suite">test suite</a>. You can use initialization functions for this.

625 An initialization function, like a <a class="reference internal" href="#test-case">test case</a>, is a plain C function with

626 a special name and signature. The name must start with <tt class="docutils literal">mu_init</tt> and it must

627 take no arguments, and return an error code (<tt class="docutils literal">0</tt> being success). For

628 example:

629 <pre class="literal-block">

630 int mu_init_something(void);

631 </pre>

632 All initialization functions are executed before any <a class="reference internal" href="#test-case">test case</a>, in an

633 <a class="reference internal" href="#implementations">implementation</a>-dependant order, and if one of them fail (returns non-zero),

634 the whole <a class="reference internal" href="#test-suite">test suite</a> is skipped immediately.

635 </div>

636 <div class="section" id="termination">

637 <h2><a class="toc-backref" href="#id20">3.6.   Termination</a></h2>

638 Termination functions are just like <a class="reference internal" href="#initialization">initialization</a> functions, but they're

639 executed after the <a class="reference internal" href="#test-case">test cases</a>, their names start with <tt class="docutils literal">mu_term</tt> and

640 they return nothing. For example:

641 <pre class="literal-block">

642 void mu_term_something(void);

643 </pre>

644 </div>

645 </div>

646 <div class="section" id="c-support">

647 <h1><a class="toc-backref" href="#id21">4.   C++ Support</a></h1>

648 You can use mutest with C++, the only care you must take is that, because of

649 C++ <a class="reference external" href="http://en.wikipedia.org/wiki/Name_mangling">name mangling</a> (and mutest relaying on function names), you must

650 declare your <a class="reference internal" href="#test-case">test cases</a> and <a class="reference internal" href="#initialization">initialization</a> and <a class="reference internal" href="#termination">termination</a> functions as

651 <tt class="docutils literal">extern "C"</tt> (see <a class="reference internal" href="#exception-test-cpp">exception_test.cpp</a> for an example).

652 <a class="reference internal" href="#checks">Checks</a> become exception-safe when using mutest with a C++ compiler, and

653 2 extra <a class="reference internal" href="#checks">checks</a> designed for C++ get defined (<a class="reference internal" href="#mu-echeck">mu_echeck()</a> and

654 <a class="reference internal" href="#mu-eensure">mu_eensure()</a>). They assert that an expression throws a particular exception.

655 </div>

656 <div class="section" id="implementations">

657 <h1><a class="toc-backref" href="#id22">5.   Implementations</a></h1>

658 There are 2 big groups of possible implementations that I can think

659 of: static and dynamic.

660 mutest comes with one implementation of each group.

661 <div class="section" id="static-implementations">

662 <h2><a class="toc-backref" href="#id23">5.1.   Static Implementations</a></h2>

663 Static implementations can be only written in C/C++ (or other language that is

664 link-compatible with C, like the <a class="reference external" href="http://www.digitalmars.com/d/">D Programming Language</a>, but since one of

665 the main goals of mutest is avoid unnecessary dependencies, you probably

666 don't want to depend on an extra language/compiler to run your tests =).

667 The main advantage is better debugging support, because you can run the <a class="reference internal" href="#test-program">test

668 program</a> in a standard debugger and see what happens with <a class="reference internal" href="#test-case">test cases</a> very

669 naturally.

670 The main disadvantage is, the <a class="reference internal" href="#test-suite">test suites</a> must be figured out in

671 compile-time, usually using some kind of code generation (if you want to

672 avoid writing repetitive code yourself). There's also a limitation in the <a class="reference internal" href="#test-case">test

673 case</a>, <a class="reference internal" href="#initialization">initialization</a> and <a class="reference internal" href="#termination">termination</a> functions names: they should be unique

674 for all the <a class="reference internal" href="#test-program">test program</a>.

675 <div class="section" id="c-implementation">

676 <h3><a class="toc-backref" href="#id24">5.1.1.   C implementation</a></h3>

677 mutest comes with a C static implementation. Only 3 files are needed:

678 <tt class="docutils literal">mutest.c</tt> (the user-independent part of the <a class="reference internal" href="#test-program">test program</a>), <tt class="docutils literal">mkmutest</tt>

679 (a bash script for generating the user-dependent part of the <a class="reference internal" href="#test-program">test program</a>)

680 and <tt class="docutils literal">mutest.h</tt> (the header file that <a class="reference internal" href="#test-suite">test suites</a> should include).

681 You can copy this 3 files to your project or install them at system-level and

682 use them globally.

683 The procedure is simple, You should compile you <a class="reference internal" href="#test-suite">test suites</a>, <tt class="docutils literal">mutest.c</tt>

684 and the generated output of <tt class="docutils literal">mkmutest</tt> as object files and link them

685 together.

686 For example:

687 <pre class="literal-block">

688 $ cc -c -o mutest.o mutest.c

689 $ cc -c -o test1.o test1.c

690 $ cc -c -o test2.o test2.c

691 $ mkmutest mutest.h test1.o test2.o | cc -xc -c -o runmutest.o -

692 $ cc -o testprg mutest.o test1.o test2.o runmutest.o

693 </pre>

694 Then you can run the <a class="reference internal" href="#test-program">test program</a> invoking it with no arguments:

695 <pre class="literal-block">

696 $ ./testprg

697 </pre>

698 <div class="section" id="mkmutest-invocation">

699 <h4><a class="toc-backref" href="#id25">5.1.1.1.   <tt class="docutils literal">mkmutest</tt> Invocation</a></h4>

700 This small script take 1 mandatory positional argument: the path to the

701 <tt class="docutils literal">mutest.h</tt> file. All remaining positional arguments should be object files

702 representing <a class="reference internal" href="#test-suite">test suites</a>.

703 </div>

704 <div class="section" id="test-program-invocation">

705 <h4><a class="toc-backref" href="#id26">5.1.1.2.   Test Program Invocation</a></h4>

706 The test program can be invoked without arguments, but can take some extra

707 options:

708 <dl class="docutils">

709 <dt><tt class="docutils literal">-v</tt></dt>

710 <dd>Be verbose. This is accumulative, when you add extra <tt class="docutils literal">-v</tt> you will

711 get extra verbosity.

712 By default, you just get failed <a class="reference internal" href="#checks">checks</a> printed. If you use a single

713 <tt class="docutils literal">-v</tt>, a summary of failed/passed <a class="reference internal" href="#test-suite">test suites</a>, <a class="reference internal" href="#test-case">test cases</a> and

714 <a class="reference internal" href="#checks">checks</a> will be printed. If an extra <tt class="docutils literal">-v</tt> is used, you'll see the current

715 <a class="reference internal" href="#test-suite">test suite</a> being executed. Another <tt class="docutils literal">-v</tt> and you'll get the current

716 <a class="reference internal" href="#test-case">test case</a>, and another one, and you'll get each <a class="reference internal" href="#checks">check</a>.

717 </dd>

718 </dl>

719 </div>

720 <div class="section" id="dependencies">

721 <h4><a class="toc-backref" href="#id27">5.1.1.3.   Dependencies</a></h4>

722 Even when dependencies are kept minimal, there always be a few ;)

723 To use this implementation you just need:

724 <ul class="simple">

725 <li>A C compiler (you already needed that, so...)</li>

726 <li>The <tt class="docutils literal">nm</tt> program (from <a class="reference external" href="http://www.gnu.org/software/binutils/">GNU Binutils</a>, included in virtually any *NIX)</li>

727 <li>The <a class="reference external" href="http://www.gnu.org/software/bash/">GNU Bash</a> shell interpreter (also included in virtually any *NIX)</li>

728 </ul>

729 </div>

730 </div>

731 </div>

732 <div class="section" id="dynamic-implementations">

733 <h2><a class="toc-backref" href="#id28">5.2.   Dynamic Implementations</a></h2>

734 Dynamic implementations, on the other hand, can be written in any language that

735 can access to shared objects. The idea is to inspect a shared object for <a class="reference internal" href="#test-suite">test

736 suites</a> and run them, without requiring any information about <a class="reference internal" href="#test-suite">test suites</a>

737 at compile time.

738 There are several advantages in this kind of implementations. The dynamic

739 nature let you completely separate the <a class="reference internal" href="#test-program">test program</a> from the user-written

740 <a class="reference internal" href="#test-suite">test suites</a> and you can choose at run-time what <a class="reference internal" href="#test-suite">test suites</a> to execute

741 by just selecting the correct shared objects. Also, <a class="reference internal" href="#test-case">test case</a>,

742 <a class="reference internal" href="#initialization">initialization</a> and <a class="reference internal" href="#termination">termination</a> functions names only have to be unique in the

743 scope of the <a class="reference internal" href="#test-suite">test suites</a>, because <a class="reference internal" href="#test-suite">test suites</a> are completely isolated in

744 separate shared objects.

745 But everything comes at a price, and the higher price to pay is

746 debuggability. It's a little harder to plug a debugger to a shared object.

747 <div class="section" id="python-implementation">

748 <h3><a class="toc-backref" href="#id29">5.2.1.   Python implementation</a></h3>

749 This implementation is much simpler and elegant than the <a class="reference internal" href="#c-implementation">C implementation</a>.

750 Only 2 files are needed: <tt class="docutils literal">mutest</tt> (<a class="reference internal" href="#test-program">test program</a> written in <a class="reference external" href="http://www.python.org/">Python</a> using

751 <a class="reference external" href="http://docs.python.org/library/ctypes.html">ctypes</a> module to access the shared object symbols) and <tt class="docutils literal">mutest.h</tt> (the

752 header file that <a class="reference internal" href="#test-suite">test suites</a> should include).

753 Since both implementations provided by mutest share the same <tt class="docutils literal">mutest.h</tt>,

754 you should define the <tt class="docutils literal">MUTEST_PY</tt> macro when compiling the <a class="reference internal" href="#test-suite">test suites</a> if

755 you will run them using this implementation.

756 As with the <a class="reference internal" href="#c-implementation">C implementation</a>, you can copy this 2 files to your project or

757 install them at system-level and use them globally.

758 The procedure is even simpler than the <a class="reference internal" href="#c-implementation">C implementation</a>: compile and link

759 you <a class="reference internal" href="#test-suite">test suites</a> as shared objects and then run the <tt class="docutils literal">mutest</tt> program

760 passing the shared objects as arguments. For example:

761 <pre class="literal-block">

762 $ cc -c -fPIC -DMUTEST_PY -o test1.o test1.c

763 $ cc -shared -o test1.so test1.o

764 $ cc -c -fPIC -DMUTEST_PY -o test2.o test2.c

765 $ cc -shared -o test2.so test2.o

766 $ mutest test1.so test2.so

767 </pre>

768 That's it.

769 <div class="section" id="mutest-invocation">

770 <h4><a class="toc-backref" href="#id30">5.2.1.1.   <tt class="docutils literal">mutest</tt> Invocation</a></h4>

771 <tt class="docutils literal">mutest</tt> program takes <a class="reference internal" href="#test-suite">test suites</a> shared objects to run as positional

772 arguments. It accepts the same options as the <a class="reference internal" href="#test-program-invocation">C implementation's test

773 program</a> and some extra options are accepted too:

774 <dl class="docutils">

775 <dt><tt class="docutils literal">--verbose</tt></dt>

776 <dd>Alias for <tt class="docutils literal">-v</tt>.</dd>

777 <dt><tt class="docutils literal">-q</tt>, <tt class="docutils literal">--quiet</tt></dt>

778 <dd>Be quiet (no output is shown at all).</dd>

779 <dt><tt class="docutils literal">-s</tt>, <tt class="docutils literal">--search</tt></dt>

780 <dd>Search for <a class="reference internal" href="#test-suite">test suites</a> (*.so) in the current directory and add them

781 to the list of <a class="reference internal" href="#test-suite">test suites</a> to run.</dd>

782 <dt><tt class="docutils literal">-h</tt>, <tt class="docutils literal">--help</tt></dt>

783 <dd>Show a help message and exit.</dd>

784 </dl>

785 </div>

786 <div class="section" id="id8">

787 <h4><a class="toc-backref" href="#id31">5.2.1.2.   Dependencies</a></h4>

788 As with the <a class="reference internal" href="#c-implementation">C implementation</a>, some minor dependencies are needed:

789 <ul class="simple">

790 <li><a class="reference external" href="http://www.python.org/">Python</a> (2.5 or later)</li>

791 <li>The <tt class="docutils literal">nm</tt> program (from <a class="reference external" href="http://www.gnu.org/software/binutils/">GNU Binutils</a>, included in virtually any *NIX)</li>

792 </ul>

793 You will need a C compiler for building the <a class="reference internal" href="#test-suite">test suites</a> too, but technically

794 is not needed by mutest itself ;)

795 </div>

796 </div>

797 </div>

798 </div>

799 <div class="section" id="reference">

800 <h1><a class="toc-backref" href="#id32">6.   Reference</a></h1>

801 <div class="section" id="mu-check">

802 <h2><a class="toc-backref" href="#id33">6.1.   <tt class="docutils literal">mu_check()</tt></a></h2>

803 <dl class="docutils">

804 <dt>Synopsis</dt>

805 <dd><tt class="docutils literal">mu_check(expression)</tt></dd>

806 <dt>Description</dt>

807 <dd>Check that the <tt class="docutils literal">expression</tt> evaluates to true. Continue with the

808 <a class="reference internal" href="#test-case">test case</a> if fail.</dd>

809 <dt>Availability</dt>

810 <dd>Always</dd>

811 <dt>Example</dt>

812 <dd><pre class="first last literal-block">

813 void mu_test(void)

814 {

815 mu_check(5 == 4); /* fail */

816 mu_check(5 == 5); /* excecuted, pass */

817 }

818 </pre>

819 </dd>

820 </dl>

821 </div>

822 <div class="section" id="mu-ensure">

823 <h2><a class="toc-backref" href="#id34">6.2.   <tt class="docutils literal">mu_ensure()</tt></a></h2>

824 <dl class="docutils">

825 <dt>Synopsis</dt>

826 <dd><tt class="docutils literal">mu_ensure(expression)</tt></dd>

827 <dt>Description</dt>

828 <dd>Check that the <tt class="docutils literal">expression</tt> evaluates to true. Interrupt the <a class="reference internal" href="#test-case">test

829 case</a> if fail.</dd>

830 <dt>Availability</dt>

831 <dd>Always</dd>

832 <dt>Example</dt>

833 <dd><pre class="first last literal-block">

834 void mu_test(void)

835 {

836 mu_ensure(5 == 4); /* fail */

837 mu_check(5 == 5); /* not excecuted */

838 }

839 </pre>

840 </dd>

841 </dl>

842 </div>

843 <div class="section" id="mu-echeck">

844 <h2><a class="toc-backref" href="#id35">6.3.   <tt class="docutils literal">mu_echeck()</tt></a></h2>

845 <dl class="docutils">

846 <dt>Synopsis</dt>

847 <dd><tt class="docutils literal">mu_echeck(class, expression)</tt></dd>

848 <dt>Description</dt>

849 <dd>Check that the <tt class="docutils literal">expression</tt> throws a specific exception <tt class="docutils literal">class</tt> (or

850 subclass). Continue with the <a class="reference internal" href="#test-case">test case</a> if fail.</dd>

851 <dt>Availability</dt>

852 <dd>C++ only</dd>

853 <dt>Example</dt>

854 <dd><pre class="first last literal-block">

855 #include <stdexcept>

856

857 extern "C"

858 {

859 void mu_test(void)

860 {

861 mu_echeck(std::exception, true); /* fail */

862 mu_echeck(std::exception,

863 throw std::runtime_error("!")); /* excecuted, pass */

864 }

865 }

866 </pre>

867 </dd>

868 </dl>

869 </div>

870 <div class="section" id="mu-eensure">

871 <h2><a class="toc-backref" href="#id36">6.4.   <tt class="docutils literal">mu_eensure()</tt></a></h2>

872 <dl class="docutils">

873 <dt>Synopsis</dt>

874 <dd><tt class="docutils literal">mu_eensure(class, expression)</tt></dd>

875 <dt>Description</dt>

876 <dd>Check that the <tt class="docutils literal">expression</tt> throws a specific exception <tt class="docutils literal">class</tt> (or

877 subclass). Interrupt the <a class="reference internal" href="#test-case">test case</a> if fail.</dd>

878 <dt>Availability</dt>

879 <dd>C++ only</dd>

880 <dt>Example</dt>

881 <dd><pre class="first last literal-block">

882 #include <stdexcept>

883

884 extern "C"

885 {

886 void mu_test(void)

887 {

888 mu_eensure(std::exception, true); /* fail */

889 mu_echeck(std::exception,

890 throw std::runtime_error("!")); /* not excecuted */

891 }

892 }

893 </pre>

894 </dd>

895 </dl>

896 </div>

897 </div>

898 <div class="section" id="about">

899 <h1><a class="toc-backref" href="#id37">7.   About</a></h1>

900 This manual was written using <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>.

901

902

903

904

905

906 </div>

907 </div>

908 </body>

909 </html>