github.com/keltia/go-ipfs@v0.3.8-0.20150909044612-210793031c63/test/sharness/README.md (about)

     1  # ipfs whole tests using the [sharness framework](https://github.com/mlafeldt/sharness/)
     2  
     3  ## Running all the tests
     4  
     5  Just use `make` in this directory to run all the tests.
     6  Run with `TEST_VERBOSE=1` to get helpful verbose output.
     7  
     8  ```
     9  TEST_VERBOSE=1 make
    10  ```
    11  
    12  The usual ipfs env flags also apply:
    13  
    14  ```sh
    15  # the output will make your eyes bleed
    16  IPFS_LOGGING=debug TEST_VERBOSE=1 make
    17  ```
    18  
    19  ## Running just one test
    20  
    21  You can run only one test script by launching it like a regular shell
    22  script:
    23  
    24  ```
    25  $ ./t0010-basic-commands.sh
    26  ```
    27  
    28  ## Debugging one test
    29  
    30  You can use the `-v` option to make it verbose and the `-i` option to
    31  make it stop as soon as one test fails.
    32  For example:
    33  
    34  ```
    35  $ ./t0010-basic-commands.sh -v -i
    36  ```
    37  
    38  ## Sharness
    39  
    40  When running "make" in this directory for the first time, sharness
    41  will be downloaded from its github repo and installed in a "lib/sharness"
    42  directory.
    43  
    44  Please do not change anything in the "lib/sharness" directory.
    45  
    46  If you really need some changes in sharness, please fork it from
    47  [its cannonical repo](https://github.com/mlafeldt/sharness/) and
    48  send pull requests there.
    49  
    50  ## Writing Tests
    51  
    52  Please have a look at existing tests and try to follow their example.
    53  
    54  When possible and not too inefficient, that means most of the time,
    55  an ipfs command should not be on the left side of a pipe, because if
    56  the ipfs command fails (exit non zero), the pipe will mask this failure.
    57  For example after `false | true`, `echo $?` prints 0 (despite `false`
    58  failing).
    59  
    60  It should be possible to put most of the code inside `test_expect_success`,
    61  or sometimes `test_expect_failure`, blocks, and to chain all the commands
    62  inside those blocks with `&&`, or `||` for diagnostic commands.
    63  
    64  ### Diagnostics
    65  
    66  Make your test case output helpful for when running sharness verbosely.
    67  This means cating certain files, or running diagnostic commands.
    68  For example:
    69  
    70  ```
    71  test_expect_success ".ipfs/ has been created" '
    72    test -d ".ipfs" &&
    73    test -f ".ipfs/config" &&
    74    test -d ".ipfs/datastore" &&
    75    test -d ".ipfs/blocks" ||
    76    test_fsh ls -al .ipfs
    77  '
    78  ```
    79  
    80  The `|| ...` is a diagnostic run when the preceding command fails.
    81  test_fsh is a shell function that echoes the args, runs the cmd,
    82  and then also fails, making sure the test case fails. (wouldnt want
    83  the diagnostic accidentally returning true and making it _seem_ like
    84  the test case succeeded!).
    85  
    86  
    87  ### Testing commands on daemon or mounted
    88  
    89  Use the provided functions in `lib/test-lib.sh` to run the daemon or mount:
    90  
    91  To init, run daemon, and mount in one go:
    92  
    93  ```sh
    94  test_launch_ipfs_daemon_and_mount
    95  
    96  test_expect_success "'ipfs add --help' succeeds" '
    97    ipfs add --help >actual
    98  '
    99  
   100  # other tests here...
   101  
   102  # dont forget to kill the daemon!!
   103  test_kill_ipfs_daemon
   104  ```
   105  
   106  To init, run daemon, and then mount separately:
   107  
   108  ```sh
   109  test_init_ipfs
   110  
   111  # tests inited but not running here
   112  
   113  test_launch_ipfs_daemon
   114  
   115  # tests running but not mounted here
   116  
   117  test_mount_ipfs
   118  
   119  # tests mounted here
   120  
   121  # dont forget to kill the daemon!!
   122  test_kill_ipfs_daemon
   123  ```