Add order-scope option

- allows to use module or class scoped ordering
- also replace ' by ", as black prefers this
- closes #2

Author: mrbean-bremen

.github/workflows/builddocs.yml

@@ -45,7 +45,7 @@ jobs:
         run: |
           cp -r main/docs/build/html/* doc/dev
           cd doc
-          git config user.name "Travis CI"
+          git config user.name "CI Build"
           git config user.email "[email protected]"
           git add dev/*
           if [ `git status -s | wc -l` = 0 ]; then

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Added
+- add configuration option for sorting scope,
+  see [#2](https://github.com/mrbean-bremen/pytest-order/issues/2)
+
 ## [Version 0.8.0](https://pypi.org/project/pytest-order/0.8.0/)
 This release is mostly related to the consolidation of infrastructure
 (documentation build and tests in CI build) and documentation.  

docs/source/conf.py

@@ -27,36 +27,36 @@
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
+# needs_sphinx = "1.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.coverage',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages',  # puts .nojekyll file into source
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.coverage",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",  # puts .nojekyll file into source
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The encoding of source files.
-# source_encoding = 'utf-8-sig'
+# source_encoding = "utf-8-sig"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = u'pytest-order'
-copyright = u'2014, Frank Tobia'
+project = u"pytest-order"
+copyright = u"2014, Frank Tobia"
 
-# The version info for the project you're documenting, acts as replacement for
+# The version info for the project you"re documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
@@ -72,9 +72,9 @@
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-# today = ''
+# today = ""
 # Else, today_fmt is used as the format for a strftime call.
-# today_fmt = '%B %d, %Y'
+# today_fmt = "%B %d, %Y"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -84,7 +84,7 @@
 # documents.
 # default_role = None
 
-# If true, '()' will be appended to :func: etc. cross-reference text.
+# If true, "()" will be appended to :func: etc. cross-reference text.
 # add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
@@ -96,7 +96,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -109,7 +109,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'nature'
+html_theme = "nature"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -145,9 +145,9 @@
 # directly to the root of the documentation.
 # html_extra_path = []
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# If not "", a "Last updated on:" timestamp is inserted at every page bottom,
 # using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
+# html_last_updated_fmt = "%b %d, %Y"
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -181,33 +181,33 @@
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
-# html_use_opensearch = ''
+# html_use_opensearch = ""
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 # html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pytest-orderdoc'
+htmlhelp_basename = "pytest-orderdoc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    # The paper size ("letterpaper" or "a4paper").
+    # "papersize": "letterpaper",
 
-    # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    # The font size ("10pt", "11pt" or "12pt").
+    # "pointsize": "10pt",
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    # "preamble": "",
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ('index', 'pytest-order.tex', u'pytest-order Documentation',
-     u'Frank Tobia', 'manual'),
+    ("index", "pytest-order.tex", u"pytest-order Documentation",
+     u"Frank Tobia", "manual"),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -236,8 +236,8 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'pytest-order', u'pytest-order Documentation',
-     [u'Frank Tobia'], 1)
+    ("index", "pytest-order", u"pytest-order Documentation",
+     [u"Frank Tobia"], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -250,9 +250,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    ('index', 'pytest-order', u'pytest-order Documentation',
-     u'Frank Tobia', 'pytest-order', 'One line description of project.',
-     'Miscellaneous'),
+    ("index", "pytest-order", u"pytest-order Documentation",
+     u"Frank Tobia", "pytest-order", "One line description of project.",
+     "Miscellaneous"),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -261,8 +261,8 @@
 # If false, no module index is generated.
 # texinfo_domain_indices = True
 
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-# texinfo_show_urls = 'footnote'
+# How to display URL addresses: "footnote", "no", or "inline".
+# texinfo_show_urls = "footnote"
 
-# If true, do not generate a @detailmenu in the "Top" node's menu.
+# If true, do not generate a @detailmenu in the "Top" node"s menu.
 # texinfo_no_detailmenu = False

docs/source/index.rst

@@ -121,7 +121,7 @@ There are currently three possibilities to define the order:
 Order by number
 ---------------
 As already shown above, the order can be defined using ordinal numbers.
-Negative numbers are also allowed - they are used the same way as indexes
+Negative numbers are also allowed--they are used the same way as indexes
 are used in Python lists, e.g. to count from the end:
 
 .. code:: python
@@ -265,7 +265,9 @@ by their name:
 
 Configuration
 =============
-Currently there is only one option that changes the behavior of the plugin.
+Currently there are two command line option that change the behavior of the
+plugin. As for any option, you can add the options to your ``pytest.ini`` if
+you want to have them always applied.
 
 ``--indulgent-ordering``
 ------------------------
@@ -284,6 +286,24 @@ pytest-order *before* the sort from ``--failed-first``, allowing the failed
 tests to be sorted to the front (note that in pytest versions from 6.0 on,
 this seems not to be needed anymore, at least in this specific case).
 
+``--order-scope``
+-----------------
+By default, tests are ordered per session, e.g. across all modules in the
+test run. Sometimes, you want to order tests per module or per test class
+instead. Consider that you have a growing number of test modules that you
+want to run simultaneously, with tests ordered per module. Per default you
+would need to make sure that the order numbers increases globally, if you
+want to run the test modules consecutively and order the test per module.
+
+If you use the option ``--order-scope=module``, there is no need for this.
+You can enumerate your tests starting with 0 or 1 in each module, and the tests
+will only be ordered inside each module. Using ``--order-scope=class``
+additionally considers test classes--each test class is considered
+separately for ordering the tests. If a module has both test classes and
+separate test functions, these test functions are handled separately from the
+test classes. If a module has no test classes, the effect is the same as
+if using ``--order-scope=module``.
+
 Miscellaneous
 =============
 

example/test_ordinals.py

@@ -1,21 +1,21 @@
 import pytest
 
 
-@pytest.mark.order('second_to_last')
+@pytest.mark.order("second_to_last")
 def test_three():
     assert True
 
 
-@pytest.mark.order('last')
+@pytest.mark.order("last")
 def test_four():
     assert True
 
 
-@pytest.mark.order('second')
+@pytest.mark.order("second")
 def test_two():
     assert True
 
 
-@pytest.mark.order('first')
+@pytest.mark.order("first")
 def test_one():
     assert True

example/test_other.py

@@ -1,11 +1,11 @@
 import pytest
 
 
-@pytest.mark.order2
+@pytest.mark.order(2)
 def test_foo():
     assert True
 
 
-@pytest.mark.order1
+@pytest.mark.order(1)
 def test_bar():
     assert True

example/test_quickstart.py

@@ -1,7 +1,7 @@
 import pytest
 
 
-@pytest.mark.order(after='test_second')
+@pytest.mark.order(after="test_second")
 def test_third():
     assert True
 
@@ -10,6 +10,6 @@ def test_second():
     assert True
 
 
-@pytest.mark.order(before='test_second')
+@pytest.mark.order(before="test_second")
 def test_first():
     assert True

example/test_relative.py

@@ -0,0 +1,31 @@
+import pytest
+
+
+class Test1:
+    @pytest.mark.order("last")
+    def test_two(self):
+        assert True
+
+    @pytest.mark.order("first")
+    def test_one(self):
+        assert True
+
+
+class Test2:
+    @pytest.mark.order("last")
+    def test_two(self):
+        assert True
+
+    @pytest.mark.order("first")
+    def test_one(self):
+        assert True
+
+
+@pytest.mark.order("last")
+def test_two():
+    assert True
+
+
+@pytest.mark.order("first")
+def test_one():
+    assert True

fixture/test_classes.py

@@ -0,0 +1,11 @@
+import pytest
+
+
+@pytest.mark.order("last")
+def test_two():
+    assert True
+
+
+@pytest.mark.order("first")
+def test_one():
+    assert True