[CT-744] [Bug] document for test

[bachng2017]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

dbt docs generate does not generate correct description for tests in tests folder.

Expected Behavior

With current yml, dbt docs should create correct description for the test

---
version: 2
tests:
  - name: a_test
    description: this is a test

Steps To Reproduce

• create a sql and correspond yam in tests folder

  ---
  version: 2
  tests:
    - name: a_test
      description: this is a test
  

• run dbt docs generate
• check the document by browser

Relevant log output

no error just usual logs

12:38:43  Running with dbt=1.1.0
12:38:43  Found 4 models, 1 test, 0 snapshots, 0 analyses, 151 macros, 0 operations, 1 seed file, 0 sources, 0 exposures, 0 metrics
12:38:43
12:38:43  Concurrency: 1 threads (target='test')
12:38:43
12:38:44  Done.
12:38:44  Building catalog
12:38:44  Catalog written to [my_path]/sample/target/catalog.json

### Environment

• OS: Ubuntu
• Python: 3.8
• dbt: 1.1.0

### What database are you using dbt with?

other (mention it in "Additional Context")

### Additional Context

trino/hive

[jtcohen6]

Hey @bachng2017, thanks for opening!

Adding a description to tests actually isn't something that dbt supports today, although it's been on our minds for some time:

• Allow instances of generic data tests to be documented #2578
• Configurable description in yaml config for generic tests #3249

To clarify what you're after, are you trying to add a description to a "singular" test (one-off .sql file defined in tests/), or a "generic" test (macro-like, reused across your project)? We'd like to eventually support both, and the latter requires a bigger lift.

Meta note: I'm going to close this issue as a duplicate of those two linked above, but I am still curious to hear more about your intended use case!

[bachng2017]

thanks for the comments and sorry about the duplication. I mentioned about the "singular" test. For the generic tests, they could be documented fine likes other macros.

As you mentioned the feature is not planned., it's OK. My point is that, currently dbt docs generate generates the page like this for a singular test. It makes people confused that somehow you are supporting the feature.

will check the tickets above but just wonder why support test document is not planned :) Because for testing, document is vital imho

[johalnes]

Having used some hours, with the occasional thinking of how stupid am I to not be able to make this work, I'll second @bachng2017 in that the description is confusing. I was 100% sure this should work because of that description text.

@jtcohen6 - Coming from financial reporting, beeing able to test is perfect. But there is a lot of filtering to be able to test a company's financial statement vs detailed reporting, and from experience this logic will be forgotten sometime early in 2023. Making this feature almost as important as describing models and macros.