* Adding a new test

To add a new test in this folder, just add a new folder with a descriptive
name with some sources and an =expectation.json= file with some commands to
run through =rc= and the expected resulting locations.

- The directory must start with a specific word to classify the test, those are ::

  + Location
  + Parsing
  + Completion
  + Output

  If it doesn't start with one of those it is considered to be a _Location_ test.

  Those types of tests are handled with the test file _test\_misc.py_. For
  bigger tests consider using a separate test file.

* RTags Sandbox Root Test

Running the RTags server, rdm, with --sandbox-root=DIR instructs the RTags server to create the
index database using relative paths to DIR. This is very useful for 're-using' index
databases. Consider a large C++ project consisting of many modules, where each module consists of
many C++ source files. The term sandbox refers to the directory containing the project. For example,
we could have a sandbox root at DIR consisting of N modules and many C++ files:

#+BEGIN_EXAMPLE
DIR/module1/FILES
DIR/module2/FILES
...
DIR/moduleN/FILES
#+END_EXAMPLE

Next we ask RTags to create a relative index, in DIR/.rtags/rtags_db:

#+BEGIN_SRC bash
mkdir -p DIR/.rtags/rtags_db
rdm --socket-file=DIR/.rtags/rdm_socket \
    --no-rc \
    --data-dir=DIR/.rtags/rtags_db \
    --log-file=DIR/.rtags/rtags.log \
    --crash-dump-file=DIR/.rtags/crash_dump.txt \
    --job-count=12 \
    --watch-sources-only \
    --sandbox-root=DIR
# index C++ FILES by running rc --compile or rc --load-compilation-database, etc.
#+END_SRC


Suppose you use this as a master sandbox. Team members can then copy/clone the DIR sandbox using
rsync, btrfs, etc. e.g.

     rsync DIR/ DIR1
     or
     btrfs subvolume snapshot DIR DIR1

After the copy or clone operation, DIR1 is a 'deep copy' of DIR which can be immediately navigated
(after starting another instance of rdm for DIR1).

** Testing --sandbox-root=DIR

The =test_sbroot.py= is a small pthon pytest test that runs on a 'mock' sandbox
project to validate the --sandbox-root handling in RTags. =test_sbroot.py= asks
rdm to index the project. Then the project is moved to another directory
simulating the copy operation. The move operation ensures the navigation queries
in the moved sandbox don't refer to the original sandbox because the original
sandbox no longer exits.

*** Usage

#+BEGIN_SRC bash
RTAGS_BINARY_DIR=/path/to/rtags/bin pytest test_sbroot.py
#+END_SRC

The test driver =test_sbroot.py= reads the
=tests/automated/sbroot_test/expectation.json= to determine what to test.
