draft port of the smoke tests doc from the wiki.

draft/smoke-tests.txt

@@ -0,0 +1,166 @@
+===========
+Smoke Tests
+===========
+
+
+Test Organization
+-----------------
+
+# :file:`dbtests/.*cpp` has C++ unit tests
+# :file:`jstests/*.js` has core tests
+# :file:`jstests/repl*/*.js` has replication tests
+# :file:`jstests/sharding/*.js` has sharding tests
+# :file:`slowNightly/*js` has tests that take longer and run only at night
+# :file:`slowWeekly/*.js` has tests that take even longer and run only once a week
+
+Running all the tests
+---------------------
+
+.. code-block:: sh
+
+   scons smoke smokeCppUnittests smokeDisk smokeTool smokeAuth startMongod smokeClient smokeJs
+   scons startMongodSmallOplog smokeJs
+   scons startMongod smokeJsSlowNightly
+   scons smokeTool
+   scons smokeReplSets
+   scons smokeDur
+   scons mongosTest smokeSharding
+   scons smokeRepl smokeClone
+   scons startMongod smokeParallel
+
+smoke.py
+--------
+
+:file:`smoke.py` lets you run a subsets of the tests in :file:`jstests/`.
+When it is running tests, it starts up an instance of mongod, runs the tests,
+and then shuts it down again.
+You can run it while running other instances of MongoDB on the same machine:
+it uses ports in the 30000 range and its own data directories.
+
+For the moment, :file:`smoke.py` must be run from the top-level directory
+of a MongoDB source repository.
+This directory must contain at least the :program:`mongo` and
+:program:`mongod` binaries.
+To run certain tests, you'll also need to build the tools and :program:`mongos`.
+It's a good idea to run ``scons .`` before running the tests.
+
+To run :file:`smoke.py` you'll need a recent version of
+`PyMongo <http://api.mongodb.org/python/current/installation.html>`_.
+
+To see the possible options, run:
+
+.. code-block:: sh
+
+   $ python buildscripts/smoke.py --help
+   Usage: smoke.py [OPTIONS] ARGS*
+
+   Options:
+     -h, --help            show this help message and exit
+     --mode=MODE           If "files", ARGS are filenames; if "suite", ARGS are
+                           sets of tests (suite)
+     --test-path=TEST_PATH
+                           Path to the test executables to run, currently only
+                           used for 'client' (none)
+     --mongod=MONGOD_EXECUTABLE
+                           Path to mongod to run (/Users/mike/10gen/mongo/mongod)
+     --port=MONGOD_PORT    Port the mongod will bind to (32000)
+     --mongo=SHELL_EXECUTABLE
+                           Path to mongo, for .js test files
+                           (/Users/mike/10gen/mongo/mongo)
+     --continue-on-failure
+                           If supplied, continue testing even after a test fails
+     --from-file=FILE      Run tests/suites named in FILE, one test per line, '-'
+                           means stdin
+     --smoke-db-prefix=SMOKE_DB_PREFIX
+                           Prefix to use for the mongods' dbpaths ('')
+     --small-oplog         Run tests with master/slave replication & use a small
+                           oplog
+
+
+.. note::
+
+   By default, :file:`smoke.py` will run tests that create data in :file:`/data/db`,
+   which may interfere with other MongoDB instances you are running.
+   To change the directory in which the smoke tests create databases, use
+   ``--smoke-db-prefix=/some/other/path``
+
+To run specific tests, use the :option:`--mode=files` option:
+
+.. code-block:: sh
+
+   python buildscripts/smoke.py --mode=files jstests/find1.js
+
+You can specify as many files as you want.
+
+You can also run a suite of tests.  Suites are predefined and include:
+
+* _test_
+* _all_
+* _perf_
+* _js_
+* _quota_
+* _jsPerf_
+* _disk_
+* _jsSlowNightly_
+* _jsSlowWeekly_
+* _parallel_
+* _clone_
+* _repl_ (master/slave replication tests)
+* _replSets_ (replica set tests)
+* _auth_
+* _sharding_
+* _tool_
+* _client_
+* _mongosTest_
+
+To run a suite, specify the suite's name:
+
+.. code-block::
+
+   python buildscripts/smoke.py js
+
+
+Running a jstest manually
+-------------------------
+
+You can run a jstest directly from the shell, for example:
+
+.. code-block:: sh
+
+   mongo --nodb jstests/replsets/replsetarb3.js
+
+Running the C++ unit tests
+--------------------------
+
+The tests under jstests/ folder are written in mongo shell javascript.
+However there are a set of C++ unit tests also.  To run them:
+
+.. code-block:: sh
+
+   scons test
+   ./test
+
+
+Build the unit tests (in src/mongo/unittest/ by running:
+
+.. code-block:: sh
+
+   $ scons build/unittests.txt
+   /* build output */
+   Generating build/unittests.txt
+           build/linux2/dd/durableDefaultOff/mongo/platform/atomic_word_test
+           ...
+           build/linux2/dd/durableDefaultOff/mongo/bson_template_evaluator_test
+           build/linux2/dd/durableDefaultOff/mongo/balancer_policy_test
+   scons: done building targets.
+
+Then use the line above to run the binary generated:
+
+.. code-block:: sh
+
+   $ ./build/linux2/dd/durableDefaultOff/mongo/platform/atomic_word_test
+
+
+.. see-also::
+
+   * `scons <http://www.scons.org/>`_