Skip to content

Ghidra is a software reverse engineering (SRE) framework

19.4 KB
Raw Blame
/* ###
 * IP: GHIDRA
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package generic.test;

import static org.junit.Assert.*;

import java.io.File;
import java.io.IOException;
import java.util.*;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.function.BooleanSupplier;
import java.util.function.Supplier;

import org.junit.Assert;
import org.junit.Rule;
import org.junit.rules.TestName;
import org.junit.rules.TestRule;

import generic.test.rule.*;
import ghidra.framework.Application;
import ghidra.framework.TestApplicationUtils;
import ghidra.util.SystemUtilities;
import ghidra.util.UniversalIdGenerator;
import ghidra.util.exception.AssertException;
import junit.framework.AssertionFailedError;
import utility.application.ApplicationUtilities;

/**
 * A root for system tests that provides known system information.
 *
 * <P>
 * This class exists so that fast unit tests have a place to share data without having the slowness
 * of more heavy weight concepts like {@link Application}, logging, etc.
 *
 * <P>
 * !! WARNING !! This test is meant to initialize quickly. All file I/O should be avoided.
 */
public abstract class AbstractGTest {

	static {
		// Ensure that UniversalIDGenerator is initialized
		UniversalIdGenerator.initialize();
	}

	public final static boolean BATCH_MODE = SystemUtilities.isInTestingBatchMode();
	protected final static boolean PARALLEL_MODE = Boolean.parseBoolean(
		System.getProperty("ghidra.test.property.parallel.mode", Boolean.FALSE.toString()));

	// currently set to 200ms in parallel mode; we can increase as needed; too long slows tests
	public static final int DEFAULT_WAIT_DELAY = 10 * (PARALLEL_MODE ? 20 : 1);
	public static final int DEFAULT_WAIT_TIMEOUT = 2000 * (PARALLEL_MODE ? 10 : 1);
	public static final int DEFAULT_WINDOW_TIMEOUT = DEFAULT_WAIT_TIMEOUT;

	// Note: these start with PRIVATE in order to discourage direct test usage
	// 5x longer than normal
	protected static final int PRIVATE_LONG_WAIT_TIMEOUT = DEFAULT_WAIT_TIMEOUT * 5;
	// 10x longer than normal
	// private static final int PRIVATE_MAX_WAIT_TIMEOUT = DEFAULT_WAIT_TIMEOUT * 10;

	// let this get created lazily so that subclasses can change system state first
	private static String testDirectoryPath; //  = createTestDirectoryPath();

	@Rule
	public TestName testName = new TestName();

	/**
	 * This rule handles the {@link Repeated} annotation
	 *
	 * <p>
	 * During batch mode, this rule should never be needed. This rule is included here as a
	 * convenience, in case a developer wants to use the {@link Repeated} annotation to diagnose a
	 * non-deterministic test failure. Without this rule, the annotation would be silently ignored.
	 */
	@Rule
	public TestRule repeatedRule = new RepeatedTestRule();

	/**
	 * This rule handles the {@link IgnoreUnfinished} annotation
	 */
	@Rule
	public TestRule ignoreUnfinishedRule = new IgnoreUnfinishedRule();

	/**
	 * Get the directory path within which all temporary test data files should be created.  This
	 * method will only initialize the test directory path one time.
	 */
	private static void initializeTestDirectoryPath() {
		if (testDirectoryPath == null) {
			//
			// Build unique test data directory.  Note that we can't make any calls which
			// depend upon Application initialization, so we have to create directories using
			// knowledge of how our environments are setup.
			//
			if (BATCH_MODE) {
				testDirectoryPath = buildBatchDirectoryPath();
			}
			else {
				testDirectoryPath = buildDevelopmentDirectoryPath();
			}
		}

		File testDir = new File(testDirectoryPath);
		if (!testDir.exists()) {
			if (!testDir.mkdirs()) {
				throw new AssertException("Failed to create temp directory: " + testDir);
			}
			System.out.println("Created test directory: " + testDir);
		}
	}

	private static String buildBatchDirectoryPath() {
		//
		// In batch mode we rely on the fact that the test environment has been setup with a
		// custom temp directory.
		//
		try {
			return new File(ApplicationUtilities.getDefaultUserTempDir("ghidra"),
				"test_" + UUID.randomUUID() + File.separator + "temp.data").getPath();
		}
		catch (IOException e) {
			throw new AssertException(e);
		}
	}

	private static String buildDevelopmentDirectoryPath() {
		//
		// Create a unique name based upon the repo from which we are running.
		//
		File tempDir = TestApplicationUtils.getUniqueTempDir();
		return tempDir.getPath();
	}

	public static String getTestDirectoryPath() {
		initializeTestDirectoryPath();
		return testDirectoryPath;
	}

	public static int getRandomInt() {
		return getRandomInt(0, Integer.MAX_VALUE);
	}

	public static int getRandomInt(int min, int max) {
		int distributionLength = (max - min) + 1;// make inclusive
		double randomValueInRange = Math.random() * distributionLength;
		int randomInt = (int) randomValueInRange;
		int valueInRangeWithOffset = min + randomInt;

		// don't go beyond the max in the case where we hit the boundary above (with the +1)
		return Math.min(valueInRangeWithOffset, max);
	}

	public static String getRandomString() {
		return "STR_" + getRandomString(0, 20);
	}

	public static String getRandomString(int min, int max) {
		int stringLength = getRandomInt(min, max);
		StringBuilder buffy = new StringBuilder();
		for (int i = 0; i < stringLength; i++) {
			buffy.append((char) getRandomInt(65, 126));
		}
		return buffy.toString();
	}

	/**
	 * Compares the contents of two arrays to determine if they are equal. The contents must match
	 * in the same order. If <code>message</code> is <code>null</code>, then a generic error message
	 * will be printed.
	 *
	 * @param message The message to print upon failure; can be null
	 * @param expected The expected array.
	 * @param actual The actual array.
	 */
	public static void assertArraysEqualOrdered(String message, Object[] expected,
			Object[] actual) {

		if (expected == null) {
			assertNull(actual);
			return;
		}
		assertListEqualOrdered(message, Arrays.asList(expected), Arrays.asList(actual));
	}

	/**
	 * Compares the contents of two arrays to determine if they are equal. The contents do not have
	 * to be in the same order. If <code>message</code> is <code>null</code>, then a generic error
	 * message will be printed.
	 *
	 * @param message The message to print upon failure; can be null
	 * @param expected The expected array.
	 * @param actual The actual array.
	 */
	public static void assertArraysEqualUnordered(String message, Object[] expected,
			Object[] actual) {

		if (expected == null) {
			assertNull(actual);
			return;
		}
		assertListEqualUnordered(null, Arrays.asList(expected), Arrays.asList(actual));
	}

	public static void assertListEqualOrdered(List<?> expected, List<?> actual) {
		assertListEqualOrdered(null, expected, actual);
	}

	public static void assertListEqualOrdered(String message, List<?> expected, List<?> actual) {

		if (expected == null) {
			assertNull(actual);
			return;
		}

		Assert.assertEquals(printListFailureMessage(message, expected, actual), expected.size(),
			actual.size());
		for (int i = 0; i < expected.size(); i++) {
			if (!actual.get(i).equals(expected.get(i))) {
				Assert.fail(printListFailureMessage(message, expected, actual));
			}
		}
	}

	public static void assertListEqualUnordered(String message, List<?> expected, List<?> actual) {

		if (expected == null) {
			assertNull(actual);
			return;
		}

		List<?> expectedCopy = new ArrayList<>(expected);
		List<?> actualCopy = new ArrayList<>(actual);

		actualCopy.removeAll(expected);
		expectedCopy.removeAll(actual);

		if (actualCopy.isEmpty() && expectedCopy.isEmpty()) {
			// all expected items accounted for in the actual values
			return;
		}

		// OK, one or both lists had extra data
		if (message == null) {
			message = "\tExpected collections to be the same; " +
				"one or both collections had extra items - difference:" +
				"\n\n\n\t'Expected' unique values: " + expectedCopy +
				";\n\t'Actual' unique values:      " + actualCopy + "\n\n";
		}
		fail(message);
	}

	@SafeVarargs
	public static <T> void assertListEqualsArrayOrdered(List<T> actual, T... expected) {
		assertListEqualOrdered(null, Arrays.asList(expected), actual);
	}

	public static void assertListEqualsArrayUnordered(List<?> actual, Object... expected) {
		assertListEqualUnordered(null, Arrays.asList(expected), actual);
	}

	/**
	 * Compares the contents of two arrays to determine if they are equal
	 *
	 * @param expected The expected array.
	 * @param actual The actual array.
	 */
	public static void assertArraysEqualUnordered(String[] expected, String[] actual) {
		assertArraysEqualUnordered(null, expected, actual);
	}

	@SafeVarargs
	public static <T> void assertContainsExactly(Collection<T> collection, T... expected) {
		List<T> asList = Arrays.asList(expected);

		Set<T> expectedSet = new HashSet<>(collection);
		Set<T> actualSet = new HashSet<>(asList);

		expectedSet.removeAll(asList);
		actualSet.removeAll(collection);

		if (!actualSet.isEmpty()) {
			Assert.fail("Collection did not contain expected results.\nExpected: " + asList +
				"\nFound: " + collection);
		}
		if (!expectedSet.isEmpty()) {
			Assert.fail("collection also contained extra results: " + expectedSet);
		}
	}

	public static <T> void assertContainsExactly(Collection<T> expected, Collection<T> actual) {

		Set<T> expectedSet = new HashSet<>(expected);
		Set<T> actualSet = new HashSet<>(actual);

		expectedSet.removeAll(actual);
		actualSet.removeAll(expected);

		if (!actualSet.isEmpty()) {
			Assert.fail("Actual collection had more entries than expected.\nExpected: " + expected +
				"\nFound:      " + actual);
		}

		if (!expectedSet.isEmpty()) {
			Assert.fail(
				"Expected collection had these entries not found in the actual collection: " +
					expectedSet);
		}
	}

	public static <T> void assertContainsString(String expected, String actual) {
		assertTrue("String not contained.  Found: '" + actual + "'\n\tExpected to contain: '" +
			expected + "'", actual.contains(expected));
	}

	public static <T> void assertContainsStringIgnoringCase(String expected, String actual) {
		assertTrue("String not contained.  Found: '" + actual + "'\n\tExpected to contain: '" +
			expected + "'", actual.toLowerCase().contains(expected.toLowerCase()));
	}

	private static String printListFailureMessage(String message, List<?> expected,
			List<?> actual) {

		StringBuffer buffer = new StringBuffer();
		buffer.append("Expected: ").append(expected.toString());
		buffer.append(" Found: ").append(actual.toString());
		buffer.toString();

		if (message == null) {
			return buffer.toString();
		}

		return message + "\n\n" + buffer;
	}

	public static void failWithException(String message, Throwable e) {
		AssertionError error = new AssertionError(message);
		error.initCause(e);
		throw error;
	}

	/**
	 * Returns the current test method name
	 *
	 * @return the current test method name
	 */
	public String getName() {
		return testName.getMethodName();
	}

	/**
	 * Friendly way to create an array of bytes with static values.
	 *
	 * @param unsignedBytes var-args list of unsigned byte values (ie. 0..255)
	 * @return array of bytes
	 */
	public static byte[] bytes(int... unsignedBytes) {
		byte[] result = new byte[unsignedBytes.length];
		for (int i = 0; i < unsignedBytes.length; i++) {
			result[i] = (byte) unsignedBytes[i];
		}
		return result;
	}

//==================================================================================================
// Wait Methods
//==================================================================================================

	public static long sleep(long timeMs) {

		long start = System.currentTimeMillis();
		try {
			Thread.sleep(timeMs);
		}
		catch (InterruptedException e) {
			// don't care
		}

		long end = System.currentTimeMillis();
		return end - start;
	}

	/**
	 * Waits for the given latch to be counted-down
	 *
	 * @param latch the latch to await
	 * @throws AssertionFailedError if the condition is not met within the timeout period
	 */
	public static void waitFor(CountDownLatch latch) {
		try {
			if (!latch.await(DEFAULT_WAIT_TIMEOUT, TimeUnit.MILLISECONDS)) {
				throw new AssertionFailedError("Timed-out waiting for CountDownLatch");
			}
		}
		catch (InterruptedException e) {
			fail("Interrupted waiting for CountDownLatch");
		}
	}

	/**
	 * Waits for the given AtomicBoolean to return true. This is a convenience method for
	 * {@link #waitFor(BooleanSupplier)}.
	 *
	 * @param ab the atomic boolean
	 * @throws AssertionFailedError if the condition is not met within the timeout period
	 */
	public static void waitFor(AtomicBoolean ab) throws AssertionFailedError {
		waitForCondition(() -> ab.get());
	}

	/**
	 * Waits for the given condition to return true
	 *
	 * @param condition the condition that returns true when satisfied
	 * @throws AssertionFailedError if the condition is not met within the timeout period
	 */
	public static void waitFor(BooleanSupplier condition) throws AssertionFailedError {
		waitForCondition(condition);
	}

	/**
	 * Waits for the given condition to return true
	 *
	 * @param condition the condition that returns true when satisfied
	 * @throws AssertionFailedError if the condition is not met within the timeout period
	 */
	public static void waitForCondition(BooleanSupplier condition) throws AssertionFailedError {
		waitForCondition(condition, "Timed-out waiting for condition");
	}

	/**
	 * Waits for the given condition to return true
	 *
	 * @param condition the condition that returns true when satisfied
	 * @param failureMessage the message to print upon the timeout being reached
	 * @throws AssertionFailedError if the condition is not met within the timeout period
	 */
	public static void waitForCondition(BooleanSupplier condition, String failureMessage)
			throws AssertionFailedError {

		waitForCondition(condition, true /*failOnTimeout*/, failureMessage);
	}

	/**
	 * Waits for the given condition to return true
	 *
	 * @param condition the condition that returns true when satisfied
	 * @param failureMessageSupplier the function that will supply the failure message in the event
	 *            of a timeout.
	 * @throws AssertionFailedError if the condition is not met within the timeout period
	 */
	public static void waitForCondition(BooleanSupplier condition,
			Supplier<String> failureMessageSupplier) throws AssertionFailedError {

		waitForCondition(condition, true /*failOnTimeout*/, failureMessageSupplier);
	}

	/**
	 * Waits for the given condition to return true. Most of the <code>waitForCondition()</code>
	 * methods throw an {@link AssertionFailedError} if the timeout period expires. This method
	 * allows you to setup a longer wait period by repeatedly calling this method.
	 *
	 * <P>
	 * Most clients should use {@link #waitForCondition(BooleanSupplier)}.
	 *
	 * @param supplier the supplier that returns true when satisfied
	 */
	public static void waitForConditionWithoutFailing(BooleanSupplier supplier) {
		waitForCondition(supplier, false /*failOnTimeout*/, () -> null /*failure message*/);
	}

	private static void waitForCondition(BooleanSupplier condition, boolean failOnTimeout,
			String failureMessage) throws AssertionFailedError {

		waitForCondition(condition, failOnTimeout, () -> failureMessage);
	}

	private static void waitForCondition(BooleanSupplier condition, boolean failOnTimeout,
			Supplier<String> failureMessageSupplier) throws AssertionFailedError {

		int totalTime = 0;
		while (totalTime <= DEFAULT_WAIT_TIMEOUT) {

			if (condition.getAsBoolean()) {
				return; // success
			}

			totalTime += sleep(DEFAULT_WAIT_DELAY);
		}

		if (!failOnTimeout) {
			return;
		}

		String failureMessage = "Timed-out waiting for condition";
		if (failureMessageSupplier != null) {
			failureMessage = failureMessageSupplier.get();
		}

		throw new AssertionFailedError(failureMessage);
	}

	/**
	 * Waits for the value returned by the supplier to be non-null, throwing an exception if that
	 * does not happen by the default timeout.
	 *
	 * @param supplier the supplier of the value
	 * @param failureMessage the message to print upon the timeout being reached
	 * @return the non-null value
	 * @throws AssertionFailedError if a non-null value is not returned within the timeout period
	 */
	public static <T> T waitFor(Supplier<T> supplier, String failureMessage) {
		return waitForValue(supplier, failureMessage, true);
	}

	/**
	 * Waits for the value returned by the supplier to be non-null, throwing an exception if that
	 * does not happen by the default timeout.
	 *
	 * @param supplier the supplier of the value
	 * @return the non-null value
	 * @throws AssertionFailedError if a non-null value is not returned within the timeout period
	 */
	public static <T> T waitFor(Supplier<T> supplier) {
		return waitForValue(supplier);
	}

	/**
	 * Waits for the value returned by the supplier to be non-null, throwing an exception if that
	 * does not happen by the default timeout.
	 *
	 * @param supplier the supplier of the value
	 * @return the non-null value
	 * @throws AssertionFailedError if a non-null value is not returned within the timeout period
	 */
	public static <T> T waitForValue(Supplier<T> supplier) {
		return waitForValue(supplier, null, true /*failOnTimeout*/);
	}

	/**
	 * Waits for the value returned by the supplier to be non-null. If the timeout period expires,
	 * then null will be returned. Most of the <code>waitXyz()</code> methods throw an
	 * {@link AssertionFailedError} if the timeout period expires. This method allows you to setup a
	 * longer wait period by repeatedly calling this method.
	 *
	 * <P>
	 * Most clients should use {@link #waitForValue(Supplier)}.
	 *
	 * @param supplier the supplier of the value
	 * @return the value; may be null
	 * @see #waitForValue(Supplier)
	 */
	public static <T> T waitForValueWithoutFailing(Supplier<T> supplier) {
		return waitForValue(supplier, null, false /*failOnTimeout*/);
	}

	/**
	 * Waits for the value returned by the supplier to be non-null, optionally throwing an exception
	 * if that does not happen by the given timeout.
	 *
	 * @param supplier the supplier of the value
	 * @param failureMessage the message to print upon the timeout being reached
	 * @param failOnTimeout if true, an exception will be thrown if the timeout is reached
	 * @return the value
	 * @throws AssertionFailedError if a non-null value is not returned within the timeout period
	 */
	private static <T> T waitForValue(Supplier<T> supplier, String failureMessage,
			boolean failOnTimeout) {
		int totalTime = 0;
		while (totalTime <= DEFAULT_WAIT_TIMEOUT) {

			T t = supplier.get();
			if (t != null) {
				return t; // success
			}

			totalTime += sleep(DEFAULT_WAIT_DELAY);
		}

		if (!failOnTimeout) {
			return null;
		}

		String error =
			failureMessage != null ? failureMessage : "Timed-out waiting for non-null value";
		throw new AssertionFailedError(error);
	}

//==================================================================================================
// End Wait Methods
//==================================================================================================
}