🐛 Bug: Escape special characters for markdown reporter

[frantic1048]

If I put any character has a special meaning in markdown, into the describe message. Run Mocha with -R md .The output markdown will have wrong semantic with any special character in messages.

Just write test like this:

describe('***', function() {
  describe('\\\\', function() {
    it('>>> should be escaped');
  });
});

Markdown would have:

# TOC
   - [***](#)
     - [\\](#-)
<a name=""></a>

<a name=""></a>
# ***
<a name="-"></a>
## \\

The special characters changed markdown output's semantic, finally brings out a strange look.

[ScottFreeCode]

Hmm. I get this output instead:

# TOC
   - [***](#)
     - [\\](#-)
<a name=""></a>

<a name=""></a>
# ***
<a name="-"></a>
## \\

...or, if I add an empty function to the it call so it's not pending:

# TOC
   - [***](#)
     - [\\](#-)
<a name=""></a>

<a name=""></a>
# ***
<a name="-"></a>
## \\
>>> should be escaped.

\`\`\`js

\`\`\`

(NOTE: "`" should be "`"... I can't seem to find any way to escape this, but as far as I can tell that's the way it's supposed to be done...)

That, frankly, doesn't look correct either (what's with the blank names?)...

I'm also not sure why it's outputting the <a> tags in the first place when GitHub flavored Markdown tends to treat # as linkable, for that matter -- but maybe there's something I've overlooked in that regard.

Does anyone know how this should be handling these cases?

For visualization, original reported output renders like this:

***

\

.

And my output renders like this:

TOC

• ***
  • \

***

\

and

TOC

• ***
  • \

***

\

should be escaped.

[frantic1048]

My bad for the careless report.

I think it needs to just escape the message content, then add markdown markups on escaped content.

[boneskull]

I don't even know what the use-case is for the Markdown reporter. Once we can understand that, we can determine how it should work. Evidently, people are using it. Why?

cc @frantic1048 @thomas88

[frantic1048]

@boneskull For my case, I was writing test for a lexical analyzer.

I'm using various characters to describe what test cases contain, to say This case is for Identifiers, This case is for unexpected tokens, # should be unexpected token.

So I wish the special characters in test case description to be literally presented.

[ScottFreeCode]

One possible use for the Markdown reporter specifically, in my mind, is throwing the output of a test up on a Gist or a GitHub comment or any blog with Markdown support. I don't know if anyone's currently doing that, but it'd be neat if A) it can be done and turns out better than just throwing other reporters' output into a code block and B) it's highlighted in the documentation or otherwise helped to become well-known.

[thmsobrmlr]

@boneskull I was planning to put the generated markdown files for my React component tests in a docs/ folder. Thus it would serve well as documentation for the components.

[ScottFreeCode]

I think @thomas88's use case fits very nicely with the idea that tests also serve as a kind of documentation of the intended behavior that (unlike other forms of documentation) will tell you if it gets out of sync. If you're writing tests with an eye to documenting the tested code (and not everybody is, but it is a school of thought out there), why not reuse that as at least part of the documentation proper? :+1:

[stale[bot]]

I am a bot that watches issues for inactivity. This issue hasn't had any recent activity, and I'm labeling it stale. In 14 days, if there are no further comments or activity, I will close this issue. Thanks for contributing to Mocha!