From 545976f1941c1822b21a8be3effcc4d873735138 Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Thu, 7 Nov 2024 20:42:51 -0500
Subject: [PATCH] Minor: Document how to test for trailing whitespace in `slt`
 / sqllogictests (#13215)

* Minor: Document how to test for trailing whitespace

* Apply suggestions from code review

Co-authored-by: Piotr Findeisen <piotr.findeisen@gmail.com>

* Use `|` for consistency

---------

Co-authored-by: Piotr Findeisen <piotr.findeisen@gmail.com>
---
 datafusion/sqllogictest/README.md             | 33 +++++++++++++++++++
 .../sqllogictest/test_files/functions.slt     | 21 ++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/datafusion/sqllogictest/README.md b/datafusion/sqllogictest/README.md
index 5becc75c985a..885e92fee270 100644
--- a/datafusion/sqllogictest/README.md
+++ b/datafusion/sqllogictest/README.md
@@ -102,6 +102,39 @@ SELECT * from foo;
 
 Assuming it looks good, check it in!
 
+## Cookbook: Testing for whitespace
+
+The `sqllogictest` runner will automatically strip trailing whitespace, meaning
+it requires an additional effort to verify that trailing whitespace is correctly produced
+
+For example, the following test can't distinguish between `Andrew` and `Andrew `
+(with trailing space):
+
+```text
+query T
+select substr('Andrew Lamb', 1, 7)
+----
+Andrew
+```
+
+To test trailing whitespace, project additional non-whitespace column on the
+right. For example, by selecting `'|'` after the column of interest, the test
+can distinguish between `Andrew` and `Andrew `:
+
+```text
+# Note two spaces between `Andrew` and `|`
+query TT
+select substr('Andrew Lamb', 1, 7), '|'
+----
+Andrew  |
+
+# Note only one space between `Andrew` and `|`
+query TT
+select substr('Andrew Lamb', 1, 6), '|'
+----
+Andrew |
+```
+
 # Reference
 
 ## Running tests: Validation Mode
diff --git a/datafusion/sqllogictest/test_files/functions.slt b/datafusion/sqllogictest/test_files/functions.slt
index 5b6017b08a00..a7568d88f797 100644
--- a/datafusion/sqllogictest/test_files/functions.slt
+++ b/datafusion/sqllogictest/test_files/functions.slt
@@ -735,3 +735,24 @@ query B
 select contains('', '');
 ----
 true
+
+
+## Demonstrate how to test for trailing whitespace
+
+# Note no trailing whitespace
+query T
+select substr('Andrew Lamb', 1, 7)
+----
+Andrew
+
+# Note two spaces between `Andrew` and `|`
+query TT
+select substr('Andrew Lamb', 1, 7), '|'
+----
+Andrew  |
+
+# Note only one space between `Andrew` and `|`
+query TT
+select substr('Andrew Lamb', 1, 6), '|'
+----
+Andrew |