Skip to content
Browse files

Update README.

  • Loading branch information...
1 parent 81b90b1 commit 3ba9611dde5535d96e8b2f73dcd2443cea943436 @nvie committed
Showing with 72 additions and 57 deletions.
  1. +72 −57 README.rst
View
129 README.rst
@@ -27,16 +27,34 @@ Usage
``test_<filename>.py``)
2. Press ``<F8>`` to run ``nosetests`` on it
-It shows the errors inside a quickfix window, which will allow your to quickly
-jump to the error locations by simply pressing ``[Enter]``.
+It shows the errors inside a quickfix window, which will allow your to
+quickly jump to the error locations by simply pressing ``[Enter]``.
Source files vs. test files
---------------------------
-``vim-pyunit`` assumes that you have a single test file for each Python source
-file. The settings ``test_prefix``, ``test_suffix``, ``source_root``,
-``tests_root``, and ``tests_structure`` determine how the plugin finds which
-test files belong to which source files.
+``vim-pyunit`` assumes that you have a single test file for each Python
+source file. The settings ``PyUnitTestPrefix``, ``PyUnitSourceRoot``,
+``PyUnitTestsRoot``, and ``PyUnitTestsStructure`` determine how the plugin
+finds which test files belong to which source files.
+
+The ``PyUnitTestsStructure`` setting is the most important one, because it
+determines where the PyUnit plugin searches for source and test files.
+There are three options:
+
+* **flat**: Put all test files in a single test directory. File names are
+ composed by resembling the source's module structure, using underscores
+ as separators. For example, the test file for the source file
+ ``foo/bar.py`` is called ``tests/test_foo_bar.py``.
+* **side-by-side**: Put all the test files in the same directory as the
+ source files. Test files are prefixed with ``test_``. For example, the
+ test file for the source file ``foo/bar.py`` is called
+ ``foo/test_bar.py``. Use this setting when testing Django apps.
+* **follow-hierarchy**: Put all the test files in a separate test
+ directory (specified by ``PyUnitTestsRoot``), but keep the same
+ directory hierarchy as used in the source directory.
+ For example, the test file for the source file ``foo/bar.py`` is called
+ ``tests/test_foo/test_bar.py``.
Keyboard mappings
@@ -44,26 +62,23 @@ Keyboard mappings
By default, the ``vim-pyunit`` plugin defines the following keyboard
mappings:
-+----------+------------------------------------------------------------------+
-| Keymap | Description |
-+==========+==================================================================+
-| F8 | Run ``nosetests`` for the current file. This mapping can be used |
-| | on both the source file, and on its corresponding test file. |
-| | |
-| | Calls ``PyUnitRunTests()`` |
-+----------+------------------------------------------------------------------+
-| Shift+F8 | Run ``nosetests`` for all test files in the project, this is |
-| | equivalent to running ``nosetests`` in the root of your project. |
-| | |
-| | Calls ``PyUnitRunAllTests()`` |
-+----------+------------------------------------------------------------------+
-| F9 | Switch between the source and the corresponding test file. If |
-| | the source or test file is not yet open, it is opened. The |
-| | setting ``tests_split_window`` is used to determine where the |
-| | file needs to be opened screen-wise. |
-| | |
-| | Calls ``PyUnitSwitchToCounterpart()`` |
-+----------+------------------------------------------------------------------+
++----------+------------------------------------------------------------+
+| Keymap | Description |
++==========+============================================================+
+| F8 | Run ``nosetests`` for the current file. This mapping can |
+| | be used on both the source file, and on its corresponding |
+| | test file. Calls ``PyUnitRunTests()`` |
++----------+------------------------------------------------------------+
+| Shift+F8 | Run ``nosetests`` for all test files in the project, this |
+| | is equivalent to running ``nosetests`` in the root of your |
+| | project. Calls ``PyUnitRunAllTests()`` |
++----------+------------------------------------------------------------+
+| F9 | Switch between the source and the corresponding test file. |
+| | If the source or test file is not yet open, it is opened. |
+| | The setting ``tests_split_window`` is used to determine |
+| | where the file needs to be opened screen-wise. Calls |
+| | ``PyUnitSwitchToCounterpart()`` |
++----------+------------------------------------------------------------+
The plugin autodetects whether you have remapped the functions to custom
keyboard mappings. If so, if does not register the default mappings. So to
@@ -85,37 +100,37 @@ Configuration
-------------
The plugin supports setting of the following variables:
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| Variable | Description | Values | Default |
-+===============================+================================================+==============================+=======================================+
-| ``PyUnitShowTests`` | Shows the tests. | 0 or 1 | ``1`` |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``PyUnitCmd`` | The command to run the unit test. | any string | ``"nosetests -q --with-machineout"`` |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``ProjRootIndicators`` | List of filenames indicating the | list of file names | ``[".git", "setup.py", "setup.cfg"]`` |
-| | project root. | | |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``ProjRootStopAtHomeDir`` | Stop the search for the project root at the | 0 or 1 | ``1`` |
-| | user's home dir. | | |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``PyUnitTestPrefix`` | The filename prefix to use for test files. | any string | ``"test_"`` |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``PyUnitTestSuffix`` | *Not implemented yet* | 0 or 1 | n/a |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``PyUnitSourceRoot`` | The relative location where all source files | directory spec, or empty | ``""`` |
-| | live. | | |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``PyUnitTestRoot`` | The relative location where all tests live. | directory spec | ``"tests"`` |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``PyUnitTestStructure`` | Specifies how you wish to organise your tests. | flat, follow-hierarchy | ``"follow-hierarchy"`` |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``PyUnitTestsSplitWindow`` | Specifies where test files should be opened, | left, right, top, bottom, no | ``"right"`` |
-| | when oopened next to the source file. When set | | |
-| | to ``no``, doesn't open a new window at all, | | |
-| | but reuses the current buffer. | | |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
-| ``PyUnitConfirmTestCreation`` | Ask to confirm creation of new test files. | 0 or 1 | ``1`` |
-+-------------------------------+------------------------------------------------+------------------------------+---------------------------------------+
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| Variable | Description | Values | Default |
++===============================+================================================+===========================+===================================+
+| ``PyUnitShowTests`` | Shows the tests. | 0 or 1 | 1 |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``PyUnitCmd`` | The command to run the unit test. | any string | "nosetests -q --with-machineout" |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``ProjRootIndicators`` | List of filenames indicating the project root. | list of file names | [".git", "setup.py", "setup.cfg"] |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``ProjRootStopAtHomeDir`` | Stop the search for the project root at the | 0 or 1 | 1 |
+| | user's home dir. | | |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``PyUnitTestPrefix`` | The filename prefix to use for test files. | any string | "test_" |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``PyUnitTestSuffix`` | *Not implemented yet* | 0 or 1 | n/a |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``PyUnitSourceRoot`` | The relative location where all source files | directory spec, or empty | "" |
+| | live. | | |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``PyUnitTestsRoot`` | The relative location where all tests live. | directory spec | "tests" |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``PyUnitTestsStructure`` | Specifies how you wish to organise your tests. | flat, follow-hierarchy, | "follow-hierarchy" |
+| | | side-by-side | |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``PyUnitTestsSplitWindow`` | Specifies where test files should be opened, | left, right, top, bottom, | "right" |
+| | when oopened next to the source file. When set | no | |
+| | to ``no``, doesn't open a new window at all, | | |
+| | but reuses the current buffer. | | |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
+| ``PyUnitConfirmTestCreation`` | Ask to confirm creation of new test files. | 0 or 1 | 1 |
++-------------------------------+------------------------------------------------+---------------------------+-----------------------------------+
Tips

0 comments on commit 3ba9611

Please sign in to comment.
Something went wrong with that request. Please try again.