/*******************************************************************************
* Copyright (c) 2000, 2008 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* Brock Janiczak (brockj@tpg.com.au)
* - https://bugs.eclipse.org/bugs/show_bug.cgi?id=102236: [JUnit] display execution time next to each test
*******************************************************************************/
package org.phpsrc.eclipse.pti.tools.phpunit.core.model;
/**
* Common protocol for test elements. This set consists of
* {@link ITestCaseElement} , {@link ITestSuiteElement} and
* {@link ITestRunSession}
*
* <p>
* This interface is not intended to be implemented by clients.
* </p>
*
*
* @since 3.3
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface ITestElement {
/**
* Running states of a test.
*/
public static final class ProgressState {
/** state that describes that the test element has not started */
public static final ProgressState NOT_STARTED = new ProgressState("Not Started"); //$NON-NLS-1$
/** state that describes that the test element has is running */
public static final ProgressState RUNNING = new ProgressState("Running"); //$NON-NLS-1$
/**
* state that describes that the test element has been stopped before
* being completed
*/
public static final ProgressState STOPPED = new ProgressState("Stopped"); //$NON-NLS-1$
/** state that describes that the test element has completed */
public static final ProgressState COMPLETED = new ProgressState("Completed"); //$NON-NLS-1$
private String fName;
private ProgressState(String name) {
fName = name;
}
public String toString() {
return fName;
}
}
/**
* Result states of a test.
*/
public static final class Result {
/** state that describes that the test result is undefined */
public static final Result UNDEFINED = new Result("Undefined"); //$NON-NLS-1$
/** state that describes that the test result is 'OK' */
public static final Result OK = new Result("OK"); //$NON-NLS-1$
/** state that describes that the test result is 'Error' */
public static final Result ERROR = new Result("Error"); //$NON-NLS-1$
/** state that describes that the test result is 'Failure' */
public static final Result FAILURE = new Result("Failure"); //$NON-NLS-1$
/** state that describes that the test result is 'Ignored' */
public static final Result IGNORED = new Result("Ignored"); //$NON-NLS-1$
private String fName;
private Result(String name) {
fName = name;
}
public String toString() {
return fName;
}
}
/**
* A failure trace of a test.
*
* This class is not intended to be instantiated or extended by clients.
*/
public static final class FailureTrace {
private final String fActual;
private final String fExpected;
private final String fTrace;
public FailureTrace(String trace, String expected, String actual) {
fActual = actual;
fExpected = expected;
fTrace = trace;
}
/**
* Returns the failure stack trace.
*
* @return the failure stack trace
*/
public String getTrace() {
return fTrace;
}
/**
* Returns the expected result or <code>null</code> if the trace is not
* a comparison failure.
*
* @return the expected result or <code>null</code> if the trace is not
* a comparison failure.
*/
public String getExpected() {
return fExpected;
}
/**
* Returns the actual result or <code>null</code> if the trace is not a
* comparison failure.
*
* @return the actual result or <code>null</code> if the trace is not a
* comparison failure.
*/
public String getActual() {
return fActual;
}
}
/**
* Returns the progress state of this test element.
* <dl>
* <li>{@link ITestElement.ProgressState#NOT_STARTED}: the test has not yet
* started</li>
* <li>{@link ITestElement.ProgressState#RUNNING}: the test is currently
* running</li>
* <li>{@link ITestElement.ProgressState#STOPPED}: the test has stopped
* before being completed</li>
* <li>{@link ITestElement.ProgressState#COMPLETED}: the test (and all its
* children) has completed</li>
* </dl>
*
* @return returns one of {@link ITestElement.ProgressState#NOT_STARTED},
* {@link ITestElement.ProgressState#RUNNING},
* {@link ITestElement.ProgressState#STOPPED} or
* {@link ITestElement.ProgressState#COMPLETED}.
*/
public ProgressState getProgressState();
/**
* Returns the result of the test element.
* <dl>
* <li>{@link ITestElement.Result#UNDEFINED}: the result is not yet
* evaluated</li>
* <li>{@link ITestElement.Result#OK}: the test has succeeded</li>
* <li>{@link ITestElement.Result#ERROR}: the test has returned an error</li>
* <li>{@link ITestElement.Result#FAILURE}: the test has returned an failure
* </li>
* <li>{@link ITestElement.Result#IGNORED}: the test has been ignored
* (skipped)</li>
* </dl>
*
* @param includeChildren
* if <code>true</code>, the returned result is the combined
* result of the test and its children (if it has any). If
* <code>false</code>, only the test's result is returned.
*
* @return returns one of {@link ITestElement.Result#UNDEFINED},
* {@link ITestElement.Result#OK}, {@link ITestElement.Result#ERROR}
* , {@link ITestElement.Result#FAILURE} or
* {@link ITestElement.Result#IGNORED}. Clients should also prepare
* for other, new values.
*/
public Result getTestResult(boolean includeChildren);
/**
* Returns the failure trace of this test element or <code>null</code> if
* the test has not resulted in an error or failure.
*
* @return the failure trace of this test or <code>null</code>.
*/
public FailureTrace getFailureTrace();
/**
* Returns the parent test element container or <code>null</code> if the
* test element is the test run session.
*
* @return the parent test suite
*/
public ITestElementContainer getParentContainer();
/**
* Returns the test run session.
*
* @return the parent test run session.
*/
public ITestRunSession getTestRunSession();
/**
* Returns the estimated total time elapsed in seconds while executing this
* test element. The total time for a test suite includes the time used for
* all tests in that suite. The total time for a test session includes the
* time used for all tests in that session.
* <p>
* <strong>NOTE</strong>: The elapsed time is only valid for
* {@link ITestElement.ProgressState#COMPLETED} test elements.
* </p>
*
* @return total execution time for the test element in seconds, or
* {@link Double#NaN}</code> if the state of the element is not
* {@link ITestElement.ProgressState#COMPLETED}
*
* @since 3.4
*/
public double getElapsedTimeInSeconds();
}