[PATCH] D68061: [docs] Document pattern of using CHECK-SAME to skip irrelevant lines

[Jordan Rupprecht via Phabricator via llvm-commits]

rupprecht created this revision.
rupprecht added a reviewer: jhenderson.
Herald added subscribers: llvm-commits, thopre.
Herald added a project: LLVM.

This came up during the review for D67656 <https://reviews.llvm.org/D67656>. It's nice but also subtle, so documenting it as an idiom will make tests easier to understand.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D68061

Files:
  llvm/docs/CommandGuide/FileCheck.rst


Index: llvm/docs/CommandGuide/FileCheck.rst
===================================================================
--- llvm/docs/CommandGuide/FileCheck.rst
+++ llvm/docs/CommandGuide/FileCheck.rst
@@ -285,8 +285,57 @@
    ; CHECK-SAME:              scope: ![[SCOPE:[0-9]+]]
 
 "``CHECK-SAME:``" directives reject the input if there are any newlines between
-it and the previous directive.  A "``CHECK-SAME:``" cannot be the first
-directive in a file.
+it and the previous directive.
+
+Another common use case for "``CHECK-SAME:``" is to avoid writing matchers for
+irrelevant fields. For example, suppose you're writing a test which parses a
+tool that generates output like this:
+
+.. code-block:: text
+
+   Name: foo
+   Field1: ...
+   Field2: ...
+   Field3: ...
+   Value: 1
+
+   Name: bar
+   Field1: ...
+   Field2: ...
+   Field3: ...
+   Value: 2
+
+   Name: baz
+   Field1: ...
+   Field2: ...
+   Field3: ...
+   Value: 1
+
+To write a test that verifies ``foo`` has the value ``1``, you might first write
+this:
+
+.. code-block:: text
+
+   CHECK: Name: foo
+   CHECK: Value: 1
+
+However, this would be a bad test: if the value for ``foo`` changes, the test
+would still pass because the "``CHECK: Value: 1``" line would match the value
+from ``baz``. To fix this, you could add ``CHECK-NEXT`` matchers for every
+``FieldN:`` line, but that would be verbose, and need to be updated when
+``Field4`` is added. A more succint way to write the test using the
+"``CHECK-SAME:``" matcher would be as follows:
+
+.. code-block:: text
+
+   CHECK:      Name: foo
+   CHECK:      Value:
+   CHECK-SAME:   1
+
+This verifies that the *next* line that contains "``Value:``" has the value
+``1``.
+
+Note: a "``CHECK-SAME:``" cannot be the first directive in a file.
 
 The "CHECK-EMPTY:" directive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D68061.221853.patch
Type: text/x-patch
Size: 1834 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20190925/ca1e1480/attachment.bin>