Junit5: Document JUnit 5 Platform Idea

[jlink]

There is hardly any _official_ documentation about how to use and add to the JUnit 5 platform.
This might be useful for users of JUnit, for possible contributors of engines and for IDE and tools developrs.

Deliverables

The follow list is just a first attempt at enumerating useful documents:

• [ ] What is the JUnit Platform all about?
• [ ] How to discover and run platform tests from any engine
• [ ] How to write and test a test engine for the JUnit platform
• [ ] How to enhance platform reporting and tooling

I guess the whole platform topic is too specific for the general JUnit 5 user guide

[marcphilipp]

I'm sure you're aware of the "Advanced Topics" chapter in the current user guide that demonstrates how to run tests using the Launcher API and how to use Testkit to test a custom engine. If I understand you correctly, you think what's missing is guides/tutorials for different use cases. Is that right?

[sormuras]

Interesting that you created this topic today, @jlink -- I drafted a blog post called "Roll Your Own Test Engine" this very morning. It starts with:

The User Guide of JUnit 5 has a section named Plugging in your own Test Engine.
[...]
This section briefly explains ways to register a custom Test Engine and ends with some notes and warnings about reserved names. But that's it. No further documentation is provided on how to roll your own. This blog post closes this gap ... soon.

In other words: yes, there should be an _official_ documentation about the JUnit Platform. A dedicated section in the User Guide could be good place for it, as it is the foundation for Jupiter and Vintage.

[sormuras]

/cc @khmarbaise + @svenruppert + @richardstartin - you might be interested in (helping out with creating, reviewing of, providing examples for) this JUnit Platform documentation as well.

[jlink]

Maybe collecting some links to existing resources would be a good start. Besides your upcoming blog post, some of my talks about that topic are online and I could update the slides to reflect the current version.

[svenruppert]

I can add my stuff about Custom TestEngines for example.

[khmarbaise]

Currently I'm working on

How to discover and run platform tests from any engine

If I'm at the state that it works I could collect some information......