Package ghidra.test

Class TestEnv

java.lang.Object
ghidra.test.TestEnv
public class TestEnv extends Object

  • Constructor Details

    • TestEnv

      public TestEnv() throws IOException
      Constructor for Ghidra A new test project is established. If it already exists it will first be deleted.
      Throws:
      IOException - if there is an issue creating a test project

    • TestEnv

      public TestEnv(String projectName) throws IOException
      Constructor for Ghidra A new test project is established using the specified projectName. If it already exists it will first be deleted. If the test environment is not disposed within 1 minute the tests iwll be aborted
      Parameters:
      projectName - the name of the project
      Throws:
      IOException - if there is an issue creating a test project

    • TestEnv

      public TestEnv(long abortTimeout, String projectName) throws IOException
      Constructor for Ghidra A new test project is established using the specified projectName. If it already exists it will first be deleted.
      Parameters:
      abortTimeout - number of minutes within which this test environment must be disposed. If not disposed in a timely manner, System.exit will be invoked.
      projectName - the name of the project
      Throws:
      IOException - if there is an issue creating a test project

    • TestEnv

      protected TestEnv(GhidraProject project)
      This constructor allows clients to manage their own projects. Also, this constructor will not enforce having only a single env instance running, which allows for multi-project testing. All other constructors will enforce that a single instance of TestEnv can be running at one time, closing any previously opened instances before finishing construction.

      Note: this constructor is meant for subclasses.

      Parameters:
      project - the initialized project

  • Method Details

    • getTool

      public PluginTool getTool()
      Get the tool associated with this test environment.
      Returns:
      the default test tool for this environment

    • closeTool

      public void closeTool()
      Closes the TestEnv's default tool. This method is asynchronous, so you must wait for the Swing thread to perform the work yourself. Watch out for modal dialogs.

    • closeTool

      public void closeTool(PluginTool toolToClose)
      Closes the given tool. This method is asynchronous, so you must wait for the Swing thread to perform the work yourself. Watch out for modal dialogs.
      Parameters:
      toolToClose - The tool to close.

    • closeTool

      public void closeTool(PluginTool toolToClose, boolean ignoreChanges)

    • disposeFrontEndTool

      protected void disposeFrontEndTool()

    • saveRestoreToolState

      public void saveRestoreToolState()

    • getPlugin

      public <T extends Plugin> T getPlugin(Class<T> c)

    • addPlugin

      public <T extends Plugin> T addPlugin(Class<T> c) throws PluginException
      Adds and returns the plugin to this env's tool for the given class.

      If you have not created a tool using this env, then the default tool from lazyTool() is used. If you have launched a tool, then that tool is used. In the following example, the given plugin is added to the default tool: 

                      TestEnv env = new TestEnv();
                env.launchDefaultTool();
                FooPlugin foo = env.addPlugin(FooPlugin.class);
      Parameters:
      c - the plugin class
      Returns:
      the plugin instance
      Throws:
      PluginException - if there is an exception adding the given tool

    • showTool

      public PluginTool showTool()
      Shows any previously created tool, creating a simple empty tool if not tool has yet been created.

      This method is considered sub-standard and users should prefer instead launchDefaultTool() or launchDefaultTool(Program).

      Returns:
      the newly shown tool

    • showTool

      public PluginTool showTool(Program p)
      Shows any previously created tool, creating a simple empty tool if not tool has yet been created. The given program will be opened in the tool.

      This method is considered sub-standard and users should prefer instead launchDefaultTool() or launchDefaultTool(Program).

      Parameters:
      p - the program
      Returns:
      the newly shown tool

    • waitForWindow

      @Deprecated public Window waitForWindow(String title, int timeoutMS)
      Deprecated.

    • waitForDialogComponent

      @Deprecated public <T extends DialogComponentProvider> T waitForDialogComponent(Class<T> ghidraClass, int maxTimeMS)
      Deprecated.
      use instead AbstractDockingTest.waitForDialogComponent(Class)
      Waits for the first window of the given class. This method is the same as waitForDialogComponent(Class, int) with the exception that the parent window is assumed to be this instance's tool frame.
      Parameters:
      ghidraClass - The class of the dialog the user desires
      maxTimeMS - The max amount of time in milliseconds to wait for the requested dialog to appear.
      Returns:
      The first occurrence of a dialog that extends the given ghidraClass

    • getFrontEndTool

      public FrontEndTool getFrontEndTool()

    • getFrontEndProvider

      public ComponentProvider getFrontEndProvider()

    • showFrontEndTool

      public FrontEndTool showFrontEndTool()

    • createDefaultTool

      public PluginTool createDefaultTool()
      This method differs from launchDefaultTool() in that this method does not set the tool variable in of this TestEnv instance.
      Returns:
      the tool

    • launchDefaultTool

      public PluginTool launchDefaultTool()
      Launches the default tool of the test system ("CodeBrowser"). This method will load the tool from resources and not from the user's Ghidra settings.

      Note: Calling this method also changes the tool that this instance of the TestEnv is using, which is the reason for the existence of this method.

      Returns:
      the tool that is launched

    • launchDefaultToolByName

      protected PluginTool launchDefaultToolByName(String toolName)

    • runScript

      public ScriptTaskListener runScript(File scriptFile) throws PluginException
      Throws:
      PluginException

    • getGhidraProject

      public GhidraProject getGhidraProject()
      Returns GhidraProject associated with this environment
      Returns:
      the project

    • closeAndReopenProject

      public void closeAndReopenProject() throws IOException
      A convenience method to close and then reopen the default project created by this TestEnv instance. This will not delete the project between opening and closing and will restore the project to its previous state.
      Throws:
      IOException - if any exception occurs while saving and reopening

    • getProjectManager

      public ProjectManager getProjectManager()

    • getProject

      public Project getProject()

    • restartTool

      public PluginTool restartTool()

    • launchAnotherDefaultTool

      public PluginTool launchAnotherDefaultTool()
      Launches another default tool, not overwriting this env's current tool.
      Returns:
      the new tool

    • getGhidraCreatedTools

      public PluginTool[] getGhidraCreatedTools()
      Returns an array of tools spawned by the Ghidra environment. NOTE: This array will not contain any of the TestTools!
      Returns:
      an array of tools spawned by the Ghidra environment

    • connectTools

      public ToolConnection connectTools(PluginTool producer, PluginTool consumer)

    • disconnectTools

      public void disconnectTools(PluginTool producer, PluginTool consumer)

    • restoreProgram

      public DomainFile restoreProgram(String programName) throws FileNotFoundException
      Copies the specified program zip file to the JUnit test project's root folder. This means that the program will appear in the FrontEndTool as part of the project. That is the only reason to use this method vice openProgram().
      Parameters:
      programName - the name of the program zip file without the ".gzf" extension.
      Returns:
      the restored domain file
      Throws:
      FileNotFoundException - if the program file cannot be found

    • findProvidedDataTypeArchive

      public static ResourceFile findProvidedDataTypeArchive(String relativePathName)

    • restoreDataTypeArchive

      public DomainFile restoreDataTypeArchive(String relativePathName, DomainFolder domainFolder) throws Exception
      Creates a project data type archive in the indicated test project folder from the ".gdt" file indicated by the relative pathname.
      Parameters:
      relativePathName - This should be a pathname relative to the "test_resources/testdata" director or relative to the "typeinfo" directory. The name should include the ".gdt" suffix.
      domainFolder - the folder in the test project where the archive should be created
      Returns:
      the domain file that was created in the project
      Throws:
      Exception - if an exception occurs

    • saveToCache

      public void saveToCache(String progName, ProgramDB program, boolean replace, TaskMonitor monitor) throws Exception
      Save a program to the cached program store. A SaveAs will be performed on the program to its cached storage location.
      Parameters:
      progName - program name
      program - program object
      replace - if true any existing cached database with the same name will be replaced
      monitor - task monitor
      Throws:
      Exception - if already cached

    • isProgramCached

      public boolean isProgramCached(String programName)
      Determine if specified program already exists with the program cache
      Parameters:
      programName - the name
      Returns:
      true if specified program already exists with the program cache

    • removeFromProgramCache

      public void removeFromProgramCache(String programName)
      Remove specified program from cache
      Parameters:
      programName - the name

    • loadAnalyzedNotepad

      public ProgramDB loadAnalyzedNotepad()

    • getProgram

      public ProgramDB getProgram(String programName)
      Open a read-only test program from the test data directory. The returned program must be released prior to disposing this test environment.
      NOTE: Some tests rely on this method returning null when file does not yet exist within the resource area (e.g., test binaries for P-Code Tests)
      Parameters:
      programName - name of program database within the test data directory.
      Returns:
      program or null if program file not found

    • launchDefaultTool

      public PluginTool launchDefaultTool(Program program)
      Launches the default tool of the test system ("CodeBrowser") using the given program. This method will load the tool from resources and not from the user's Ghidra settings.

      Note: Calling this method also changes the tool that this instance of the TestEnv is using, which is the reason for the existence of this method.

      Parameters:
      program - The program to load into the default tool; may be null
      Returns:
      the tool that is launched

    • launchTool

      public PluginTool launchTool(String toolName)
      Launches a tool of the given name using the given domain file.

      Note: the tool returned will have auto save disabled by default.

      Parameters:
      toolName - the tool's name
      Returns:
      the tool that is launched

    • launchTool

      public PluginTool launchTool(String toolName, DomainFile domainFile)
      Launches a tool of the given name using the given domain file.

      Note: the tool returned will have auto save disabled by default.

      Parameters:
      toolName - the name of the tool to launch
      domainFile - The domain file used to launch the tool; may be null
      Returns:
      the tool that is launched

    • launchToolWithURL

      public PluginTool launchToolWithURL(String toolName, URL ghidraUrl)
      Launches a tool of the given name using the given Ghidra URL.

      Note: the tool returned will have auto save disabled by default.

      Parameters:
      toolName - the name of the tool to launch
      ghidraUrl - The Ghidra URL to be opened in tool (see GhidraURL)
      Returns:
      the tool that is launched

    • setAutoSaveEnabled

      public void setAutoSaveEnabled(boolean enabled)
      Sets the auto-save feature for all tool instances running under the FrontEndTool created by this TestEnv instance. Auto-save is off by default when testing.
      Parameters:
      enabled - true enables auto-save

    • setAutoSaveEnabled

      protected void setAutoSaveEnabled(FrontEndTool frontEndToolInstance, boolean enabled)

    • loadResourceProgramAsBinary

      public Program loadResourceProgramAsBinary(String programName, Language language, CompilerSpec compilerSpec) throws LanguageNotFoundException, IOException, CancelledException, DuplicateNameException, InvalidNameException, VersionException
      Throws:
      LanguageNotFoundException
      IOException
      CancelledException
      DuplicateNameException
      InvalidNameException
      VersionException

    • loadResourceProgramAsBinary

      public Program loadResourceProgramAsBinary(String programName, Processor processor) throws CancelledException, DuplicateNameException, InvalidNameException, VersionException, IOException
      Throws:
      CancelledException
      DuplicateNameException
      InvalidNameException
      VersionException
      IOException

    • release

      public void release(Program program)
      Release a program which was obtained from this test environment.
      Parameters:
      program - the program

    • open

      public void open(Program program)
      Opens the given program in the test tool.
      Parameters:
      program - the program to open

    • close

      public void close(Program p)
      Closes the given program, ignoring all changes, for each tool known to this TestEnv.
      Parameters:
      p - the program to close

    • dispose

      public void dispose()

    • printProgramConsumers

      protected void printProgramConsumers(Program program)

    • resetDefaultTools

      public void resetDefaultTools()