Add ExpectedToFail test extension (#551 / #676)

[Marcono1234]

Proposed commit message:

Add ExpectedToFail test extension (#551 / #676)

PR: #676

Supersedes #546 (based on the same commits of that PR):

• I did not override InvocationInterceptor.interceptTestFactoryMethod as originally proposed in Add NotWorking test extension (#551 / #546) #546 (comment) because that appears to be only the call to the factory method but not the individual test executions (?) so covering that probably does not make much sense.
• As already mentioned in the comments of Add NotWorking test extension (#551 / #546) #546, handling for exceptions which occur in @AfterEach could not be kept with the InvocationInterceptor approach.
• Due to using InvocationInterceptor this probably only supports @Test methods now, but not any dynamic tests (have not investigated that in detail though).

---

PR checklist

The following checklist shall help the PR's author, the reviewers and maintainers to ensure the quality of this project.
It is based on our contributors guidelines, especially the "writing code" section.
It shall help to check for completion of the listed points.
If a point does not apply to the given PR's changes, the corresponding entry can be simply marked as done.

Documentation (general)

• There is documentation (Javadoc and site documentation; added or updated)
• There is implementation information to describe why a non-obvious source code / solution got implemented
• Site documentation has its own .adoc file in the docs folder, e.g. docs/report-entries.adoc
• Site documentation in .adoc file references demo in src/demo/java instead of containing code blocks as text
• Only one sentence per line (especially in .adoc files)
• Javadoc uses formal style, while sites documentation may use informal style

Documentation (new extension)

• The docs/docs-nav.yml navigation has an entry for the new extension
• The package-info.java contains information about the new extension

Code

• Code adheres to code style, naming conventions etc.
• Successful tests cover all changes
• There are checks which validate correct / false usage / configuration of a functionality and there are tests to verify those checks
• Tests use AssertJ or our own PioneerAssert (which are based on AssertJ)

Contributing

• A prepared commit message exists
• The list of contributions inside README.md mentions the new contribution (real name optional)

[Marcono1234]

Have implemented this as separate method in case more InvocationInterceptor methods will be overridden in the future.

[Michael1993]

The double filtering was intentional. Could you provide your rationale for removing it?

[Marcono1234]

The comment was actually a bit misleading; I have now adjusted it.

The issue was that previously (in the current version of this project) the TestCaseAssertBase instances were always created with all test / container events, without being restricted to the type of the hasSingle...() method:

junit-pioneer/src/test/java/org/junitpioneer/testkit/assertion/PioneerAssert.java

Lines 119 to 122 in f36ee4c

	private TestCaseAssertBase assertSingleTest(long numberOfTestsWithOutcome) {
	try {
	Assertions.assertThat(numberOfTestsWithOutcome).isEqualTo(1);
	return new TestCaseAssertBase(actual.testEvents());

That happened to work because TestCaseAssertBase.throwable() previously always restricted the events to failed(), however this caused issues for this pull request when I implemented TestCaseAbortedAssert.

Therefore most hasSingle...() methods now create a TestCaseAssertBase with properly filtered events, but for the methods where this is not possible (and which therefore behave the same way they did before) I added those comments.

[nipafx]

Thanks for your work on this, @Marcono1234. I made some small changes (see 9731701, 11e03c2) and I think it's ready to be merged and released in version 1.8.0. 👍🏾

[nipafx]

Proposed commit message:

Add `@ExpectedToFail` test extension (#551 / #676)

As opposed to JUnit Jupiter's `@Disabled` annotation, this extension
executes the annotated test and then effectively flips the result:

* failed ~> ignored
* passed ~> failed

This ensures that a temporarily disabled test will get discovered
once the reason for being disabled no longer holds, so it can/must
be re-enabled by removing `@ExpectedToFail`.

PR: #676

[nipafx]

@Marcono1234 Forgot to write: Can you let us know whether the changes I made are ok? I'll wait with the merge until then.

[Marcono1234]

@nipafx, thanks, the changes look fine to me! There only seems to be one small typo.

Feel free to merge this afterwards.

[nipafx]

Thank you, @Marcono1234! 👍🏾

[nipafx]

Thanks again, for your high-quality work and patience. I just released 1.8.0 with your extensions. 🙌🏾