pysysjava.javaplugin

Support for compiling and running Java applications from the run.py of your PySys tests.

JavaPlugin

class pysysjava.javaplugin.JavaPlugin[source]

Bases: object

This is a PySys test plugin that for compiling and running Java applications from a PySys testcase (or from the runner).

You can access the methods of this class from any test using self.java.XXX. To enable this, just add it to your project configuration with an alias such as java:

<test-plugin classname="pysysjava.javaplugin.JavaPlugin" alias="java"/>

For advanced cases (compiling or starting Java from a runner class or plugin) you can also use this class as a runner plugin:

<runner-plugin classname="pysysjava.javaplugin.JavaPlugin" alias="java"/>

This plugin assumes the existence of a project property named javaHome that contains the path to the JDK, with a bin/ subdirectory containing executables such as java and javac.

Since you often want the same JVM arguments (e.g. max heap size etc), compiler arguments and classpath for many of your tests, defaults for these can be configured via properties on the plugin (and in some cases also on a per-test/per-directory basis by adding <user-data name="..." value="..."> to your pysystest.xml or pysysdirconfig.xml file. For example:

<test-plugin classname="pysysjava.javaplugin.JavaPlugin" alias="java">
        <property name="defaultJVMArgs" value="-Xmx256m -XX:+HeapDumpOnOutOfMemoryError"/>
</test-plugin>

Or:

<pysysdirconfig>
        <data>
                <user-data name="javaClasspath" value="${appHome}/target/logging-jars/*.jar"/>
                <user-data name="jvmArgs" value="-Xmx256M"/>
        </data>
</pysysdirconfig>

See below for more details about these properties.

defaultCompilerArgs = '-g'

A space-delimited string of javac arguments. By default we enable full debugging information.

You may also want to add other options such as -source and -target release version.

defaultJVMArgs = '-Xmx512m -XX:+HeapDumpOnOutOfMemoryError -XX:-UsePerfData'

A space-delimited string of JVM arguments to use by default when running java processes, unless overridden by a per-test/dirconfig jvmArgs or a jvmArgs= keyword argument.

By default the maximum heap size is limited to 512MB, but you may wish to set a larger heap limit if you are starting processes that require more memory - but be careful that the test machine has sufficient resources to cope with multiple tests running concurrently without risking out of memory conditions. Also by default the -XX:-UsePerfData option is used to avoid creation of hsperfdata_XXX files in the temp directory (typically the test output directory) which aren’t useful and can prevent test cleanup.

This is converted to a list[str] when the plugin is setup ready for use by the test. If a key named jvmArgs exists in the test or directory descriptor’s user-data that value takes precedence over the plugin property.

defaultClasspath = ''

A default classpath that will be used for Java compilation and execution, unless overridden by a per-test/dirconfig javaClasspath user-data or a classpath= keyword argument.

For details of how this plugin handles delimiters in the classpath string see toClasspathList().

This is converted to a list[str] when the plugin is setup ready for use by the test. If a key named javaClasspath exists in the test or directory descriptor’s user-data that value takes precedence over the plugin property.

compile(input=None, output='javaclasses', classpath=None, arguments=None, **kwargs)[source]

Compile Java source files into classes. By default we compile Java files from the test’s input directory to self.output/javaclasses.

For example:

self.java.compile(self.input, arguments=['--Werror'])
Parameters

  • input (str or list[str]) – Typically a directory (relative to the test Input dir) in which to search for classpaths; alternatively a list of Java source files. By default we compile source files under the test Input directory.

  • output (str) – The path (relative to the test Output directory) where the output will be written.

  • classpath (str or list[str]) – The classpath to use, or None if the self.defaultClasspath should be used (which by default is empty). The classpath can be specified as a list or a single string delimited by ;, newline or os.pathsep; see toClasspathList() for details.

  • arguments (list[str]) – List of compiler arguments such as --Werror or -nowarn (to control warn behaviour). If not specified, the defaultCompilerArgs plugin property is used.

  • kwargs – Additional keyword arguments such as timeout= will be passed to pysys.basetest.BaseTest.startProcess.

Returns

The process object, with the full path to the output dir in the info dictionary.

Return type

pysys.process.Process

startJava(classOrJar, arguments=[], classpath=None, jvmArgs=None, jvmProps={}, disableCoverage=False, stdouterr=None, **kwargs)[source]

Start a Java process to execute the specified class or .jar file.

For example:

myserver = self.java.startJava(self.project.appHome+'/my_server*.jar', ['127.0.0.1', self.getNextAvailableTCPPort()], 
        stdouterr='my_server', background=True)

self.java.defaultClasspath = [self.project.appHome+'/mydeps.jar']
self.java.compile(self.input, output=self.output+'/javaclasses', arguments=['--Werror'])
self.java.startJava('myorg.MyHttpTestClient', ['127.0.0.1', port], stdouterr='httpclient', 
        classpath=self.java.defaultClasspath+[self.output+'/javaclasses'], timeout=60)

If the project includes a writer with alias “javaCoverageWriter” then that writer is requested to add some JVM arguments to control code coverage (unless disableCoverage=True).

Parameters

  • classOrJar (str) – Either a class (from the classpath) to execute, or the path to a .jar file (an absolute path or relative to the output directory) whose manifest indicates the main class. Since some jar names contain a version number, a * glob expression can be used in the .jar file provided it matches exactly one jar and still ends with the .jar suffix.

  • arguments (list[str]) – Command line arguments for the specified class.

  • classpath (str or list[str]) – The classpath to use, or None if the self.defaultClasspath should be used (which by default is empty). The classpath can be specified as a list or a single string delimited by ;, newline or os.pathsep; see toClasspathList() for details.

  • jvmArgs (list[str]) – List of JVM arguments to pass before the class/jar name, such as -Xmx512m. If None is specified, the defaultJVMArgs plugin property is used.

  • jvmProps (dict[str,str]) – System properties to be added to the jvmArgs (each entry results in a -Dkey=value jvmArg).

  • disableCoverage (bool) – Set to True to ensure Java code coverage is not captured for this process. Code coverage can also be disabled on a per-test/directory basis by setting self.disableCoverage or adding the disableCoverage group to the pysystest.xml.

  • stdouterr (str) – The filename prefix to use for the stdout and stderr of the process (out/err will be appended), or a tuple of (stdout,stderr) as returned from pysys.basetest.BaseTest.allocateUniqueStdOutErr. The filenames can be accessed from the returned process object using .stdout/err from the returned process object.

  • kwargs – Additional keyword arguments such as stdouterr=, timeout=, onError= and background= will be passed to pysys.basetest.BaseTest.startProcess. It is strongly recommended to always include at stdouterr= since otherwise any error messages from the process will not be captured.

Returns

The process object.

Return type

pysys.process.Process

toClasspathList(classpath)[source]

Converts the specified classpath string to a list of classpath entries (or just returns the input if it’s already a list). Glob expressions such as *.jar will be expanded if the parent directory exists and there is at least one match.

If None is specified, the defaultClasspath is used (either from the test/dir descriptor’s classpath user-data or the defaultClasspath plugin property).

In this PySys plugin classpath strings can be delimited with the usual OS separator os.pathsep (e.g. : or ;), but to allow for platform-independence (given Windows uses : for drive letters), if the string contains ; or a newline separator those will be used for splitting instead. Any whitespace or empty elements will be deleted.

It is recommended to use absolute not relative paths for classpath entries.

>>> plugin = JavaPlugin()

>>> plugin.toClasspathList(['a.jar', 'b.jar'])
['a.jar', 'b.jar']

>>> plugin.toClasspathList('  a.jar  ; b.jar ; c:/foo  '])
['a.jar', 'b.jar', 'c:/foo']

>>> plugin.toClasspathList(os.pathsep.join(['a.jar', 'b.jar'])
['a.jar', 'b.jar']

>>> plugin.toClasspathList(None) is None
True