From 51a4bafeb54a722be1c8d2c55a95fd45d6aa5775 Mon Sep 17 00:00:00 2001 From: Brock Date: Wed, 4 Nov 2020 15:43:13 -0800 Subject: [PATCH 1/6] DOC: test organization --- doc/source/development/test_writing.rst | 71 +++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 doc/source/development/test_writing.rst diff --git a/doc/source/development/test_writing.rst b/doc/source/development/test_writing.rst new file mode 100644 index 0000000000000..8537c0b5b3ce3 --- /dev/null +++ b/doc/source/development/test_writing.rst @@ -0,0 +1,71 @@ +.. _test_organization: + +Test Organization +================= +Ideally, there should be one, and only one, obvious place for a test to reside. +Until we reach that ideal, these are some rules of thumb for where a test should +be located. + +1) Does your test depend only on code in pd._libs.tslibs? + This test likely belongs in one of: + - tests.tslibs + - tests.scalar + - tests.tseries.offsets + +2) Does your test depend only on code in pd._libs? + This test likely belongs in one of: + - tests.libs + - tests.groupby.test_libgroupby + +3) Is your test for an arithmetic or comparison method? + This test likely belongs in one of: + - tests.arithmetic + These are intended for tests that can be shared to test the behavior of DataFrame/Series/Index/ExtensionArray using the ``box_with_array`` fixture. + - tests.frame.test_arithmetic + - tests.series.test_arithmetic + +4) Is your test for a reduction method (min, max, sum, prod, ...)? + This test likely belongs in one of: + - tests.reductions + These are intended for tests that can be shared to test the behavior of DataFrame/Series/Index/ExtensionArray. + - tests.frame.test_reductions + - tests.series.test_reductions + - tests.test_nanops + +5) Is your test for a DataFrame or Series method? + A) Is the method a plotting method? + This test likely belongs in one of: + - tests.plotting + B) Is the method an IO method? + This test likely belongs in one of: + - tests.io + + C) Is the method an indexing method? + i) Is the method ``loc``, ``iloc``, ``at``, or ``iat``? + This test likely belongs in one of: + - tests.indexing.test_methodname + ii) Otherwise + This test likely belongs in one of: + - tests.frame.indexing.test_methodname + - tests.series.indexing.test_methodname + + D) Otherwise + This test likely belongs in one of: + - tests.series.methods.test_mymethod + - tests.frame.methods.test_mymethod + If a test can be shared between DataFrame/Series using the ``frame_or_series`` fixture, by convention it goes in tests.frame file. + - tests.generic.methods.test_mymethod + The generic/methods/ directory is only for methods with tests + that are fully parametrized over Series+DataFrame + +6) Is your test for an Index method, not depending on Series/DataFrame? + This test likely belongs in one of: + - tests.indexes + +7) Is your test for one of the pandas-provided ExtensionArrays (Categorical, DatetimeArray, TimedeltaArray, PeriodArray, IntervalArray, PandasArray, FloatArray, BoolArray, IntervalArray, StringArray)? + This test likely belongs in one of: + - tests.arrays + +8) Is your test for _all_ ExtensionArray subclasses (the "EA Interface")? + This test likely belongs in one of: + - tests.extension From f2c67b06352be53301e9461dddea3371c82858df Mon Sep 17 00:00:00 2001 From: Brock Date: Wed, 4 Nov 2020 15:47:15 -0800 Subject: [PATCH 2/6] flesh out doc --- doc/source/development/test_writing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/development/test_writing.rst b/doc/source/development/test_writing.rst index 8537c0b5b3ce3..98d4dea20765e 100644 --- a/doc/source/development/test_writing.rst +++ b/doc/source/development/test_writing.rst @@ -6,9 +6,10 @@ Ideally, there should be one, and only one, obvious place for a test to reside. Until we reach that ideal, these are some rules of thumb for where a test should be located. -1) Does your test depend only on code in pd._libs.tslibs? +1) Does your test depend only on code in ``pd._libs.tslibs``? This test likely belongs in one of: - tests.tslibs + Policy: No file in ``tests.tslibs`` should import from any pandas modules outside of ``pd._libs.tslibs`` - tests.scalar - tests.tseries.offsets From c134ca090a9e07cf68794a277ab81d581a777326 Mon Sep 17 00:00:00 2001 From: Brock Date: Wed, 4 Nov 2020 15:49:12 -0800 Subject: [PATCH 3/6] md->rst --- doc/source/development/test_writing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/development/test_writing.rst b/doc/source/development/test_writing.rst index 98d4dea20765e..d3de35da4ad27 100644 --- a/doc/source/development/test_writing.rst +++ b/doc/source/development/test_writing.rst @@ -67,6 +67,6 @@ be located. This test likely belongs in one of: - tests.arrays -8) Is your test for _all_ ExtensionArray subclasses (the "EA Interface")? +8) Is your test for *all* ExtensionArray subclasses (the "EA Interface")? This test likely belongs in one of: - tests.extension From d706ac6c86c1280199df6236dec415b16a0e6e02 Mon Sep 17 00:00:00 2001 From: Brock Date: Thu, 5 Nov 2020 09:58:22 -0800 Subject: [PATCH 4/6] Troubleshoot docbuild --- doc/source/development/index.rst | 1 + doc/source/development/test_writing.rst | 81 +++++++++++++++++-------- 2 files changed, 57 insertions(+), 25 deletions(-) diff --git a/doc/source/development/index.rst b/doc/source/development/index.rst index f8a6bb6deb52d..99f1fc505ff85 100644 --- a/doc/source/development/index.rst +++ b/doc/source/development/index.rst @@ -21,3 +21,4 @@ Development policies roadmap meeting + test_writing diff --git a/doc/source/development/test_writing.rst b/doc/source/development/test_writing.rst index d3de35da4ad27..317224b0eeb0b 100644 --- a/doc/source/development/test_writing.rst +++ b/doc/source/development/test_writing.rst @@ -1,72 +1,103 @@ .. _test_organization: -Test Organization +Test organization ================= Ideally, there should be one, and only one, obvious place for a test to reside. Until we reach that ideal, these are some rules of thumb for where a test should be located. -1) Does your test depend only on code in ``pd._libs.tslibs``? - This test likely belongs in one of: +1. Does your test depend only on code in ``pd._libs.tslibs``? +This test likely belongs in one of: + - tests.tslibs - Policy: No file in ``tests.tslibs`` should import from any pandas modules outside of ``pd._libs.tslibs`` + + .. note:: + + No file in ``tests.tslibs`` should import from any pandas modules outside of ``pd._libs.tslibs`` + - tests.scalar - tests.tseries.offsets -2) Does your test depend only on code in pd._libs? - This test likely belongs in one of: +2. Does your test depend only on code in pd._libs? +This test likely belongs in one of: + - tests.libs - tests.groupby.test_libgroupby -3) Is your test for an arithmetic or comparison method? - This test likely belongs in one of: +3. Is your test for an arithmetic or comparison method? +This test likely belongs in one of: + - tests.arithmetic - These are intended for tests that can be shared to test the behavior of DataFrame/Series/Index/ExtensionArray using the ``box_with_array`` fixture. + + .. note:: + + These are intended for tests that can be shared to test the behavior of DataFrame/Series/Index/ExtensionArray using the ``box_with_array`` fixture. + - tests.frame.test_arithmetic - tests.series.test_arithmetic -4) Is your test for a reduction method (min, max, sum, prod, ...)? - This test likely belongs in one of: +4. Is your test for a reduction method (min, max, sum, prod, ...)? +This test likely belongs in one of: + - tests.reductions - These are intended for tests that can be shared to test the behavior of DataFrame/Series/Index/ExtensionArray. + + .. note:: + These are intended for tests that can be shared to test the behavior of DataFrame/Series/Index/ExtensionArray. + - tests.frame.test_reductions - tests.series.test_reductions - tests.test_nanops -5) Is your test for a DataFrame or Series method? +5. Is your test for a DataFrame or Series method? A) Is the method a plotting method? - This test likely belongs in one of: + This test likely belongs in one of: + - tests.plotting + B) Is the method an IO method? - This test likely belongs in one of: + This test likely belongs in one of: + - tests.io C) Is the method an indexing method? i) Is the method ``loc``, ``iloc``, ``at``, or ``iat``? - This test likely belongs in one of: + This test likely belongs in one of: + - tests.indexing.test_methodname + ii) Otherwise - This test likely belongs in one of: + This test likely belongs in one of: + - tests.frame.indexing.test_methodname - tests.series.indexing.test_methodname D) Otherwise - This test likely belongs in one of: + This test likely belongs in one of: + - tests.series.methods.test_mymethod - tests.frame.methods.test_mymethod - If a test can be shared between DataFrame/Series using the ``frame_or_series`` fixture, by convention it goes in tests.frame file. + + .. note:: + + If a test can be shared between DataFrame/Series using the ``frame_or_series`` fixture, by convention it goes in tests.frame file. + - tests.generic.methods.test_mymethod - The generic/methods/ directory is only for methods with tests - that are fully parametrized over Series+DataFrame -6) Is your test for an Index method, not depending on Series/DataFrame? - This test likely belongs in one of: + .. note:: + + The generic/methods/ directory is only for methods with tests that are fully parametrized over Series/DataFrame + +6. Is your test for an Index method, not depending on Series/DataFrame? +This test likely belongs in one of: + - tests.indexes 7) Is your test for one of the pandas-provided ExtensionArrays (Categorical, DatetimeArray, TimedeltaArray, PeriodArray, IntervalArray, PandasArray, FloatArray, BoolArray, IntervalArray, StringArray)? - This test likely belongs in one of: +This test likely belongs in one of: + - tests.arrays 8) Is your test for *all* ExtensionArray subclasses (the "EA Interface")? - This test likely belongs in one of: +This test likely belongs in one of: + - tests.extension From 606a07caa10f4173a817d38527cfb7c84438e12e Mon Sep 17 00:00:00 2001 From: Brock Date: Sat, 7 Nov 2020 16:58:04 -0800 Subject: [PATCH 5/6] doc for test_item --- pandas/tests/series/methods/test_item.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pandas/tests/series/methods/test_item.py b/pandas/tests/series/methods/test_item.py index a7ddc0c22dcf4..90e8f6d39c5cc 100644 --- a/pandas/tests/series/methods/test_item.py +++ b/pandas/tests/series/methods/test_item.py @@ -1,3 +1,7 @@ +""" +Series.item method, mainly testing that we get python scalars as opposed to +numpy scalars. +""" import pytest from pandas import Series, Timedelta, Timestamp, date_range @@ -5,6 +9,7 @@ class TestItem: def test_item(self): + # We are testing that we get python scalars as opposed to numpy scalars ser = Series([1]) result = ser.item() assert result == 1 From a6e7c7240aab0dc1dba29322315e33dfb8bc6453 Mon Sep 17 00:00:00 2001 From: Brock Date: Mon, 9 Nov 2020 16:39:50 -0800 Subject: [PATCH 6/6] flesh out rules --- doc/source/development/index.rst | 2 +- doc/source/development/test_writing.rst | 78 +++++++++++++++++++------ 2 files changed, 62 insertions(+), 18 deletions(-) diff --git a/doc/source/development/index.rst b/doc/source/development/index.rst index 99f1fc505ff85..e842c827b417f 100644 --- a/doc/source/development/index.rst +++ b/doc/source/development/index.rst @@ -16,9 +16,9 @@ Development code_style maintaining internals + test_writing extending developer policies roadmap meeting - test_writing diff --git a/doc/source/development/test_writing.rst b/doc/source/development/test_writing.rst index 317224b0eeb0b..27d0f44f75633 100644 --- a/doc/source/development/test_writing.rst +++ b/doc/source/development/test_writing.rst @@ -42,36 +42,80 @@ This test likely belongs in one of: - tests.reductions .. note:: + These are intended for tests that can be shared to test the behavior of DataFrame/Series/Index/ExtensionArray. - tests.frame.test_reductions - tests.series.test_reductions - tests.test_nanops -5. Is your test for a DataFrame or Series method? - A) Is the method a plotting method? +5. Is your test for an indexing method? + This is the most difficult case for deciding where a test belongs, because + there are many of these tests, and many of them test more than one method + (e.g. both ``Series.__getitem__`` and ``Series.loc.__getitem__``) + + A) Is the test specifically testing an Index method (e.g. ``Index.get_loc``, ``Index.get_indexer``)? This test likely belongs in one of: + - tests.indexes.test_indexing + - tests.indexes.fooindex.test_indexing - - tests.plotting + Within that files there should be a method-specific test class e.g. ``TestGetLoc``. - B) Is the method an IO method? + In most cases, neither ``Series`` nor ``DataFrame`` objects should be needed in these tests. + + B) Is the test for a Series or DataFrame indexing method *other* than ``__getitem__`` or ``__setitem__``, e.g. ``xs``, ``where``, ``take``, ``mask``, ``lookup``, or ``insert``? This test likely belongs in one of: + - tests.frame.indexing.test_methodname + - tests.series.indexing.test_methodname - - tests.io + C) Is the test for any of ``loc``, ``iloc``, ``at``, or ``iat``? + This test likely belongs in one of: + - tests.indexing.test_loc + - tests.indexing.test_iloc + - tests.indexing.test_at + - tests.indexing.test_iat + + Within the appropriate file, test classes correspond to either types of indexers (e.g. ``TestLocBooleanMask``) or major use cases (e.g. ``TestLocSetitemWithExpansion``). + + See the note in section D) about tests that test multiple indexing methods. + + D) Is the test for ``Series.__getitem__``, ``Series.__setitem__``, ``DataFrame.__getitem__``, or ``DataFrame.__setitem__``? + This test likely belongs in one of: + - tests.series.test_getitem + - tests.series.test_setitem + - tests.frame.test_getitem + - tests.frame.test_setitem - C) Is the method an indexing method? - i) Is the method ``loc``, ``iloc``, ``at``, or ``iat``? - This test likely belongs in one of: + If many cases such a test may test multiple similar methods, e.g. - - tests.indexing.test_methodname + .. code-block:: python + import pandas as pd + import pandas._testing as tm - ii) Otherwise - This test likely belongs in one of: + def test_getitem_listlike_of_ints(): + ser = pd.Series(range(5)) - - tests.frame.indexing.test_methodname - - tests.series.indexing.test_methodname + result = ser[[3, 4]] + expected = pd.Series([2, 3]) + tm.assert_series_equal(result, expected) + + result = ser.loc[[3, 4]] + tm.assert_series_equal(result, expected) + + In cases like this, the test location should be based on the *underlying* method being tested. Or in the case of a test for a bugfix, the location of the actual bug. So in this example, we know that ``Series.__getitem__`` calls ``Series.loc.__getitem__``, so this is *really* a test for ``loc.__getitem__``. So this test belongs in ``tests.indexing.test_loc`` + +6. Is your test for a DataFrame or Series method? + A) Is the method a plotting method? + This test likely belongs in one of: + + - tests.plotting + + B) Is the method an IO method? + This test likely belongs in one of: + + - tests.io - D) Otherwise + C) Otherwise This test likely belongs in one of: - tests.series.methods.test_mymethod @@ -87,17 +131,17 @@ This test likely belongs in one of: The generic/methods/ directory is only for methods with tests that are fully parametrized over Series/DataFrame -6. Is your test for an Index method, not depending on Series/DataFrame? +7. Is your test for an Index method, not depending on Series/DataFrame? This test likely belongs in one of: - tests.indexes -7) Is your test for one of the pandas-provided ExtensionArrays (Categorical, DatetimeArray, TimedeltaArray, PeriodArray, IntervalArray, PandasArray, FloatArray, BoolArray, IntervalArray, StringArray)? +8) Is your test for one of the pandas-provided ExtensionArrays (Categorical, DatetimeArray, TimedeltaArray, PeriodArray, IntervalArray, PandasArray, FloatArray, BoolArray, IntervalArray, StringArray)? This test likely belongs in one of: - tests.arrays -8) Is your test for *all* ExtensionArray subclasses (the "EA Interface")? +9) Is your test for *all* ExtensionArray subclasses (the "EA Interface")? This test likely belongs in one of: - tests.extension