Proposal to Upstream Specific Navigation Test Pattern currently used to test OCaml

[PizieDust]

Currently, combobulate primarily supports a testing pattern based on static markers (e.g., ①, ②) defined in fixture files. While effective for simple end-state verification, for OCaml we have introduced a more robust navigation Pattern.
This methodology allows for testing the traversal logic of the tree rather than just the final position of the point. We propose upstreaming the helpers used in this method to provide a standardized way to test structural navigation in complex, functional languages.

• Indentation-Aware Targeting: Unlike standard searches, these tests combine re-search-forward with back-to-indentation. This ensures the point lands precisely on the keyword (e.g., let) rather than leading whitespace, which is critical for accurate Tree-sitter node activation in indented OCaml code.

• Granular Traversal Verification: Traversal is broken down into named steps. This provides high-resolution debugging; if a navigation path fails, the developer knows exactly which node transition (e.g., "move to [" or "move to number") was the breaking point.

• Vertical vs. Horizontal Validation: The method allows us to test different navigation strategies on the same code block. For example, testing both via a "down" path (parent-child) and a "next" path (sibling).

• Dynamic State Check: Instead of relying on pre-placed overlays in a fixture, this method verifies the combobulate-node-type at every single step, ensuring the Tree-sitter parser is returning the expected node category at every point of the journey.

Example:

(combobulate-step "move to [" 
  (combobulate-navigate-down) 
  (should (equal (combobulate-node-type (combobulate-node-at-point)) "["))) 

(combobulate-step "move to first number" 
  (combobulate-navigate-down) 
  (should (equal (combobulate-node-type (combobulate-node-at-point)) "number"))) 

(combobulate-step "move to second number (sibling)" 
  (combobulate-navigate-next) 
  (should (equal (combobulate-node-type (combobulate-node-at-point)) "number")))

We propose upstreaming this new testing pattern

[mickeynp]

Thanks for submitting your proposal.

Hm, maybe it's me not quite understanding this, but I do not see how your example is not possible using the existing test harness system.

In fact, that system you are proposing is a basic (as I see it) unit test pattern. Nothing wrong with that, of course, but there is a reason why Combobulate does not use that. It's impossible to reason about for even remotely complex changes to the codebase itself. One slip-up in an edit or movement core function can break a dozen tests across all languages. If you use that system (and Emacs's crude ERT harness) then you're left wondering exactly what went wrong and where and why.

Your example also just tests movement: what about editing? I mean, the concept you have can be made to work with editing also. Can you please show me what a splice up test looks like --- one with lots of nested code. Then test it two and three times in a row also to ensure the accumulated deletion also works. You will quickly realise why this system does not work well.

Combobulate has a simple (think skeleton) "macro DSL" that tries to do exactly what you are proposing. The cl-defmacro combobulate-test. I abandoned it in favour of the current fixture and marker system for the reason I described above.

Now for the specifics:

This methodology allows for testing the traversal logic of the tree rather than just the final position of the point

I don't understand. The numbered system allows for sequential, nested testing. Indeed, that is how the up/down hierarchy/sibling nav stuff works which if I recall correctly also tests the reverse movement.

If a test fails with the current harness you also get verification. Yes, they could be a little bit more granular, and yes, the harness a little bit more helpful. The current system is not perfect by any means.

Vertical vs. Horizontal Validation: The method allows us to test different navigation strategies on the same code block. For example, testing both via a "down" path (parent-child) and a "next" path (sibling).

I do not understand. Do you mean testing in the same test that you can do (example) "C-M-d x 3, C-M-n" in one test?. That is not possible with the code generator, admittedly. But I do not see why it cannot be changed to accommodate this particular pattern.

Dynamic State Check: Instead of relying on pre-placed overlays in a fixture, this method verifies the combobulate-node-type at every single step, ensuring the Tree-sitter parser is returning the expected node category at every point of the journey.

I mean sure fine you verify the node type. But what if your code takes you to a wrong place with the same node type? Ultimately movement and editing is really rather simple from a user's perspective and also for the programmer working on Combobulate: typing a key should yield a predictable outcome. That outcome is coded with markers to make it easy to trace for a human. Now I'll readily admit that the fixture system for generating file editing changes is a little baroque, but then dealing with code changes at scale, across arbitrary files, is a tricky proposition. But it does work: git will tell you after regenerating the tests if your edit or even movement changes in Combobulate (or the language definition) broke something. You get a visible diff of the difference, and a test failure also of course.

Indentation-Aware Targeting: Unlike standard searches, these tests combine re-search-forward with back-to-indentation

I get using regex to find the starting point. But back to indentation is that part of the initial find procedure?