Update .github/copilot-instructions.md

Co-authored-by: Michael R Fairhurst <MichaelRFairhurst@github.com>

Author: mbaluda

.github/copilot-instructions.md

@@ -26,3 +26,34 @@ For PRs that add new queries or modify existing queries, also consider the follo
 - Can the query be simplified further (not golfed!).
 
 In your review output, list only those checklist items that are not satisfied or are uncertain, but also report any other problems you find outside this checklist; do not mention checklist items that clearly pass.
+
+## Validating tests and .expected files
+
+The test infrastructure for CodeQL that we use in this project involves the creation of a test directory with the following structure:
+- Test root is `some/path/test/path/to/feature` (mirrors `some/path/src/path/to/query`)
+- At least one test `c` or `c++` file, typically named `test.c`/`test.cpp`, with lines annotated `// COMPLIANT` or `// NON_COMPLIANT`
+- A `.ql` file with test query logic, or a `.qlref` file referring to the production query logic
+- A matching `FOO.expected` file to go with each `FOO.ql` or `FOO.qlref`, containing the test query results for the test `c` or `c++` files
+- Note that some test directories simply have a `testref` file, to document that a certain query is tested in a different directory.
+
+As a code reviewer, it is critical to ensure that the results in the `.expected` file match the comments in the test file.
+
+The `.expected` file uses a columnar format:
+- For example, a basic row may look like `| test.cpp:8:22:8:37 | element | message |`.
+- For a query with `select x, "test"`, the columns are | x.getLocation() | x.toString() | "test" |`
+- An alert with placeholders will use `$@` in the message, and have additional `element`/`string` columns for placeholder, e.g. `| test.cpp:8:22:8:37 | ... + ... | Invalid add of $@. | test.cpp:7:5:7:12 | my_var | deprecated variable my_var |`.
+- Remember, there is one `.expected` file for each `.ql` or `.qlref` file.
+- Each `.expected` file will contain the results for all test c/cpp files.
+- The `toString()` format of QL objects is deliberately terse for performance reasons.
+- For certain queries such as "path problems", the results may be grouped into categories via text lines with the category name, e.g. `nodes` and `edges` and `problems`.
+
+Reviewing tests in this style can be tedious and error prone, but fundamental to the effectiveness of our TDD requirements in this project.
+
+When reviewing tests, it is critical to:
+- Check that each `NON_COMPLIANT` case in the test file has a row in the correct `.expected` file referring to the correct location.
+- Check that each row in each `.expected` file has a `NON_COMPLIANT` case in the test file at the correct location.
+- Check that there are no `.expected` rows that refer to test code cases marked as `COMPLIANT`, or with no comment
+- Note that it is OK if the locations of the comment are not precisely aligned with the alert 
+- Check that the alert message and placeholders are accurate and understandable.
+- Consider the "test coverage" of the query, are each of its logical statements effectively exercised  individually, collectively? The test should neither be overly bloated nor under specified.
+- Consider the edge cases of the language itself, will the analysis work in non-trivial cases, are all relevant language concepts tested here? This doesn't need to be exhaustive, but it should be thoughfully thorough.