Skip to content

Apache DataFusion SQL Query Engine

docs: show how to test error messages as plain text in sqllogictest (#27217)

Jay Zhan52a8cd947e0f
diff --git a/datafusion/sqllogictest/README.md b/datafusion/sqllogictest/README.md
index 5f86145dbc..ccd248daf7 100644
--- a/datafusion/sqllogictest/README.md
+++ b/datafusion/sqllogictest/README.md
@@ -166,6 +166,41 @@ SELECT * from foo;
Assuming it looks good, check it in!
+## Cookbook: Testing errors
+
+To check an error message, write it as plain text after `----`:
+
+```text
+statement error
+SELECT * FROM no_such_table;
+----
+DataFusion error: Error during planning: table 'datafusion.public.no_such_table' not found
+
+
+```
+
+The message must match exactly, and the block must end with **two** blank
+lines. With only one, the next record is read as part of the expected error:
+the test fails, and `--complete` deletes that record from the file.
+
+To fill in the message, write the query, then `----` and two blank lines, and
+run `--complete`.
+
+Avoid putting the whole message on the `statement error` line. There it is a
+regex, so `--complete` escapes every special character:
+
+```text
+statement error DataFusion error: Error during planning: table 'datafusion\.public\.no_such_table' not found
+SELECT * FROM no_such_table;
+```
+
+Use that line only to match part of a message:
+
+```text
+statement error no_such_table
+SELECT * FROM no_such_table;
+```
+
## Cookbook: Testing for whitespace
The `sqllogictest` runner will automatically strip trailing whitespace, meaning