org.j8unit.J8UnitTest Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of core Show documentation
The core components of J8Unit, i.e., extended test class model, runner classes, additional assertion methods ...
The newest version!
package org.j8unit;

import static org.junit.Assert.assertNotNull;
import org.junit.Test;

/**
 * 
 * Base interface of subject-under-test (SUT) based J8Unit tests. It straightforwardly specifies
 * {@linkplain #createNewSUT() a SUT factory method} to query fresh SUT instances.
 * 
 *
 * 
 * There is no technical requirement to use this interface, but its usage is strongly recommend. Using this interface
 * allows seamless combination of different J8Unit tests interfaces (even if specified by programmers of different
 * APIs).
 * 
 *
 * 
 * The implementation of {@link #createNewSUT()} can be stand-alone, but it perfectly fits to {@link org.junit.Before}
 * scenarios. Both scenarios are shown below (whereas {@code FoobarTests extends J8UnitTest}); Just adopt the
 * examples to your custom needs:
 * 
 *
 * 
 * Stand-alone implementation
 * 
 *
 *  * import org.j8unit.runners.J8Unit4;
 * import org.j8unit.usage.Foobar;
 * import org.junit.runner.RunWith;
 *
 * @RunWith(J8Unit4.class)
 * public class FoobarTestCase
 * implements FoobarTests {
 *
 *     @Override
 *     public Foobar createNewSUT() {
 *         return new Foobar();
 *     }
 *
 * }
 * 
 *
 * 
 * {@linkplain org.junit.Before}-based implementation
 * 
 *
 *  * import org.j8unit.runners.J8Unit4;
 * import org.j8unit.usage.Foobar;
 * import org.junit.runner.RunWith;
 *
 * @RunWith(J8Unit4.class)
 * public class FoobarTestCase
 * implements FoobarTests {
 *
 *     private Foobar foobar;
 *
 *     @Before
 *     public void clear() {
 *         this.foobar = new Foobar();
 *     }
 *
 *     @Override
 *     public Foobar createNewSUT() {
 *         return this.foobar;
 *     }
 *
 * }
 * 
 *
 * 
 * 
 *
 * 
 * In case the SUT is not created directly but derived from an according SUT factory, {@link FactoryBasedJ8UnitTest}
 * should be used in preference. (Most often, this is the case when running parameterised tests.)
 * 
 *
 * @see FactoryBasedJ8UnitTest
 *
 * @param 
 *            the type of the subject-under-test
 * @since 4.12
 */
@FunctionalInterface
public abstract interface J8UnitTest {

    /**
     * 
     * Factory method to create a new subject-under-test (of type {@code SUT}).
     * 
     *
     * 
     * If the specific SUT is deeply immutable (and, thus, cannot be altered in any circumstance), it is absolutely
     * allowed to return the same SUT instance each time this method is called. If, otherwise, the SUT is mutable, a
     * fresh instance must be returned to prevent any strange side-effect when asserting specific behaviour during the
     * unit tests.
     * 
     *
     * 
     * To say it clear: You do not know what specific usage will be executed on the SUT instance afterwards!
     * So, think twice before carelessly returning a single instance again and again! Keep in mind internal caches,
     * states, buffers, and further prevent SUT instances from being immutable; Immutability cannot be detected by
     * looking at the visible elements only.
     * 
     *
     * @return a new subject-under-test
     */
    public abstract SUT createNewSUT();

    /**
     * 
     * If this test fails, the creation of the subject-under-test instance failed by returning {@code null}!
     * 
     */
    @Test
    public default void subjectUnderTestMustBeNotNull() {
        assertNotNull("The subject-under-test must be a valid non-null instance!", this.createNewSUT());
    }

}