jonkeane commented on a change in pull request #12140:
URL: https://github.com/apache/arrow/pull/12140#discussion_r784122983
##########
File path: docs/source/developers/guide/step_by_step/testing.rst
##########
@@ -62,29 +62,81 @@ In this section we outline steps needed for unit testing in
Arrow.
If the tests start failing, try to recompile
PyArrow or C++.
-
+
.. note::
**Recompiling Cython**
If you only make changes to `.py` files, you do not need to
recompile PyArrow. However, you should recompile it if you make
changes in `.pyx` or `.pxd` files.
-
+
To do that run this command again:
.. code:: console
$ python setup.py build_ext --inplace
.. note::
-
+
**Recompiling C++**
Similarly, you will need to recompile the C++ code if you have
made changes to any C++ files. In this case,
- re-run the cmake commands again.
+ re-run the cmake commands again.
.. tab:: R tests
- .. TODO
+ We use `testthat <https://testthat.r-lib.org/index.html>`_ for unit
testing in R. More specifically, we use the `3rd edition of testthat
<https://testthat.r-lib.org/articles/third-edition.html>`_. On rare occasions
we might want the behaviour of the 2nd edition of testthat, which is indicated
by ``testthat::local_edition(2)``.
+
+ **Structure**
+
+ Expect the usual testthat folder structure:
+ .. TODO make sure the format the dir tree below is formatted nicely
(maybe as a code block)
+ tests
+ ├── testthat # unit test files live here
+ └── testthat.R # runs tests when R CMD check runs (e.g. with
`devtools::check()`)
+
+ Usually, most files in the ``R/`` sub-folder have a corresponding test
file in ``tests/testthat``.
+
+ **Running tests**
+
+ To run all tests in a package locally use ``devtools::test()`` in the R
console. Alternatively, you can use ``make test`` in the shell.
+
+ You can run the tests in a single test file you have open with
``devtools::test_active_file()``.
+
+ All tests are also run as part of our continuous integration (CI)
pipelines.
+
+ **Good practice**
+
+ In general any change to source code needs to be accompanied by unit
tests. All tests are expected to pass before a pull request is merged.
+
+ * Add functionality -> add unit tests
+ * Modify functionality -> update unit tests
+ * Solve a bug -> add unit test before solving it, which helps prove the
bug and its fix
+ * Performance improvements should be reflected in benchmarks (which are
also tests)
+ * An exception could be refactoring functionality that is fully covered
by unit tests
+
+ ** Testing helpers**
+
+ To complement the ``testthat`` functionality, the ``arrow`` R package
has defined a series of specific utility functions (called helpers), such as:
+
+ * Expectations - these start with ``expect_`` and are used to compare
objects
+ - for example, ``expect_altrep_roundtrip()`` compares the result
+ of a function ``fn`` run on a vector ``x`` with the result of the
+ same function run on the altrep version of ``x``. More generally,
+ expect_…_roundtrip() functions do … .. TODO _fill int the blanks_
Review comment:
Ah I didn't see these questions in my first run though (thanks Github!)
It's kind of defining what roundtrip means, but I would say something like
"They take an input, convert it to some other format (e.g. arrow) and then
convert it back, confirming that the values are the same."
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
