Improve docs and warnings for assert mode checking

Author: pschanely

crosshair/examples/check_examples_test.py

@@ -24,7 +24,7 @@ def extract_linenums(text: str) -> List[int]:
 
 def find_examples() -> Iterable[Path]:
     examples_dir = pathlib.Path(os.path.realpath(__file__)).parent
-    for path in sorted(examples_dir.glob("**/*.py")):
+    for path in sorted(examples_dir.glob("*/**/*.py")):
         if path.stem != "__init__":
             yield path
 

crosshair/main.py

@@ -860,16 +860,24 @@ def check(
     if isinstance(entities, int):
         return entities
     full_options = DEFAULT_OPTIONS.overlay(report_verbose=False).overlay(options)
-    for entity in entities:
-        debug("Check ", getattr(entity, "__name__", str(entity)))
-        for message in run_checkables(analyze_any(entity, options)):
-            line = describe_message(message, full_options)
-            if line is None:
-                continue
-            stdout.write(line + "\n")
-            debug("Traceback for output message:\n", message.traceback)
-            if message.state > MessageType.PRE_UNSAT:
-                any_problems = True
+    checkables = [c for e in entities for c in analyze_any(e, options)]
+    if not checkables:
+        extra_help = ""
+        if full_options.analysis_kind == [AnalysisKind.asserts]:
+            extra_help = "\nHINT: Ensure that your functions to analyze lead with assert statements."
+        print(
+            "WARNING: Targets found, but contain no checkable functions." + extra_help,
+            file=stderr,
+        )
+
+    for message in run_checkables(checkables):
+        line = describe_message(message, full_options)
+        if line is None:
+            continue
+        stdout.write(line + "\n")
+        debug("Traceback for output message:\n", message.traceback)
+        if message.state > MessageType.PRE_UNSAT:
+            any_problems = True
     return 1 if any_problems else 0
 
 

crosshair/main_test.py

@@ -251,19 +251,28 @@ def test_no_args_prints_usage(root):
     assert re.search(r"^usage", out)
 
 
-def DISABLE_TODO_test_assert_mode_e2e(root):
+def test_assert_mode_e2e(root, capsys: pytest.CaptureFixture[str]):
     simplefs(root, ASSERT_BASED_FOO)
-    try:
-        sys.stdout = io.StringIO()
-        exitcode = unwalled_main(["check", root / "foo.py", "--analysis_kind=asserts"])
-    finally:
-        out = sys.stdout.getvalue()
-        sys.stdout = sys.__stdout__
-    assert exitcode == 1
+    exitcode = unwalled_main(["check", str(root / "foo.py"), "--analysis_kind=asserts"])
+    (out, err) = capsys.readouterr()
+    assert err == ""
     assert re.search(
-        r"foo.py\:8\: error\: AssertionError\:  when calling foofn\(x \= 100\)", out
+        r"foo.py\:8\: error\: AssertionError\:  when calling foofn\(100\)", out
     )
     assert len([ls for ls in out.split("\n") if ls]) == 1
+    assert exitcode == 1
+
+
+def test_assert_without_checkable(root, capsys: pytest.CaptureFixture[str]):
+    simplefs(root, SIMPLE_FOO)
+    exitcode = unwalled_main(["check", str(root / "foo.py"), "--analysis_kind=asserts"])
+    (out, err) = capsys.readouterr()
+    assert (
+        err
+        == "WARNING: Targets found, but contain no checkable functions.\nHINT: Ensure that your functions to analyze lead with assert statements.\n"
+    )
+    assert out == ""
+    assert exitcode == 0
 
 
 def test_directives(root):

doc/source/changelog.rst

@@ -9,6 +9,16 @@ Next Version
   * Nothing yet!
 
 
+Version 0.0.94
+--------------
+
+  * Add missing support for the `type` statement introduced in Python 3.12.
+    (fixes `#362 <https://github.com/pschanely/CrossHair/issues/362>`__)
+  * Improve documentation and warning messages for assert-mode checking.
+    (inspired by
+    [this thread](https://github.com/pschanely/CrossHair/issues/361#issuecomment-3019563904))
+
+
 Version 0.0.93
 --------------
 

doc/source/contracts.rst

@@ -13,7 +13,7 @@ Contract Syntaxes
 CrossHair can check many different kinds of contracts; choose one that fits you best:
 
 +----------------------------------------------+--------------------------------------------------------------------------+
-| :ref:`asserts <analysis_kind_asserts>`       | Use regular Python assert statements. That's it.                         |
+| :ref:`asserts <analysis_kind_asserts>`       | Use regular Python assert statements.                                    |
 |                                              |                                                                          |
 +----------------------------------------------+--------------------------------------------------------------------------+
 | :ref:`PEP 316 <analysis_kind_pep316>`        | Docstring-based contracts.                                               |

doc/source/kinds_of_contracts.rst

@@ -31,7 +31,7 @@ Assert-based Contracts
 
 This is the lowest-investment way to use contracts with CrossHair. You just use
 regular `assert statements`_ in your code. There's **no library to import** and
-**no syntax to learn**: just use assert statements.
+**no syntax to learn**.
 
 .. _assert statements: https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement
 
@@ -61,6 +61,9 @@ statements. (it will ignore any function that does not!)
 The leading assert statement(s) are considered to be preconditions: CrossHair
 will try to find inputs that make these true.
 
+If your function does not have any preconditions, but you still want CrossHair
+to analyze it, you should add an ``assert True`` statement at the beginning.
+
 After the precondition asserts, we expect the remaining asserts to pass for all
 inputs.