discussion:make testing.md more concise and decision-oriented for contributors

Increasing Access

While working across both the client and server codebases, I noticed that the repository currently follows two different test organization models, but only one of them is documented.

Client-side (documented): tests colocated adjacent to source files

Server-side (undocumented): tests grouped inside a dedicated test/ folder per module

Based on hands-on contribution experience, I strongly lean toward the server-style test-folder model as a more scalable and contributor-friendly approach, especially for larger directories.

Feature request details

Why this matters (practical impact)

In several client component directories, there are 20–25 files, where test and story files are mixed directly with production code. This has a few concrete downsides:

• Contributors must repeatedly scan past test files to locate actual components
• It becomes harder to visually distinguish production code vs test code
• Directory navigation cost increases as the project grows
• New contributors face higher cognitive load when exploring the codebase

By contrast, the server-side pattern:

module/
  controller.js
  service.js
  test/
    controller.test.js
    service.test.js

keeps production code immediately visible, while still maintaining strong test coverage.

This suggests the repository already has a proven, scalable testing model in use — just not consistently documented or discussed.

---

Documentation concern (testing.md)

Another related observation is that testing.md is currently very long (~550 lines) and highly procedural. While thorough, it can be overwhelming for contributors who just want to answer:

• Where should I put my test?
• What pattern should I follow in this part of the codebase?

This makes it harder to quickly internalize expectations, especially for first-time contributors.

There may be an opportunity to:

• Make the document more precise and decision-oriented
• Clearly explain accepted test organization patterns
• Reduce cognitive overhead without removing useful detail

Discussion points / questions

I’d love maintainer input on the following:

1. Is the server-style test/ folder considered a preferred or more scalable pattern going forward?

2. Would it make sense to explicitly support and document this model, at least for larger modules or new code?

3. Should testing.md distinguish between:

   • Small components (adjacent tests acceptable)
   • Larger modules (grouped test folders recommended)?

4. Is there interest in making testing.md more concise and guidance-focused, possibly with a short “Quick Start / Best Practices” section?
   Maintainers (@raclim ) wdyt?

Start by reading testing.md and comparing its documented client-side test organization with the server-side test/ pattern described in the issue. Confirm the preferred approach with maintainers before changing anything; done should be a concise, decision-oriented guide that clearly explains accepted test placement and contributor next steps.