Setup and Configuration

## 4 Setup and Configuration

This chapter describes how to set up the JAXB TCK and JavaTest harness software. Before proceeding with the instructions in this chapter, be sure to install all required software, as described in Chapter 3, "Installation."

After completing the instructions in this chapter, proceed to Chapter 5, "Executing Tests," for instructions on running the JAXB TCK.

This chapter includes the following topics:

- Configuring Your Environment to Run the TCK Against the Reference Implementation

- Configuring Your Environment to Repackage and Run the TCK Against the Vendor Implementation

- Custom Configuration Handlers

- Custom Deployment Handlers

- Publishing the Test Applications

- Using the JavaTest Harness Software

- Using the JavaTest Harness Configuration GUI

### 4.1 Configuring the JAXB TCK

#### 4.1.1 TCK Configuration Concepts

JAXB 2.3 comprises of a schema compiler and a schema generator. Both are types of compilers; the former maps from a schema to Java, and the latter maps from Java to schema. For the purposes of brevity in these instructions, the term compiler refers to both the schema compiler and the schema generator.

#### GUI Versus Batch Mode

Once you have configured your JAXB TCK environment using the JavaTest GUI, you can run the tests through the GUI or in batch mode using scripts. However, you cannot edit your JAXB TCK configuration files (`*.jti`) outside the JavaTest GUI. Even though the `*.jti` configuration files are straight ASCII text, they have embedded checksum strings to ensure validity and consistency with the requirements of the JAXB TCK suite.

Batch mode is particularly useful after you have worked out the basics of your test configurations through the JavaTest GUI. Batch mode provides a convenient way to automate your test runs, and also allows you to change work and report directories, which is often desirable when running tests repeatedly over progressive builds.

#### Using the JAXB TCK Configuration Interfaces

You can configure the JAXB TCK and the JavaTest harness from the JavaTest GUI, or by passing configuration parameters directly on the command line in a command shell.

JAXB TCK Configuration With the JavaTest GUI

1. Start the JavaTest harness GUI. See Section, "Starting the JavaTest Harness".

2. Complete the JavaTest harness Quick Start Wizard or use the Test Manager menu to perform the following tasks:

   - Select File and then Open Test Suite to open a test suite.

   - Select File and then New Work Dir to create a new work directory, or File and then Open Work Dir to open an existing work directory.

   - Select Configure then New Configuration to create a new configuration, Configure then Load Configuration to load an existing configuration, or Configure and then Change Values to modify the current configuration for your test environment.
     The JavaTest harness opens the configuration editor window. See the JavaTest Harness User’s Guide: Graphical User Interface included with this release or the JavaTest harness online help for detailed instructions on using the configuration editor window.

   - Click Start Running Tests on the Test Manager tool bar , or select Run Tests and then Start from the Test Manager menu.
     See the JavaTest Harness User’s Guide: Graphical User Interface included with this release or the JavaTest harness online help for detailed instructions about running the tests.

#### TCK Configuration From the JavaTest Command Line

To run the tests non-interactively, for example as part of a product build process, use the JavaTest harness command-line interface. To run tests from the command line, you must use a configuration file. The JavaTest harness command-line interface provides a number of commands that you can use to specify individual configuration values used to run tests. Values that are set in the command line will override but not change the values in the configuration file. Permanent changes to the configuration are made by using the Configuration Editor to change the values in the configuration file.

See the JavaTest Harness User’s Guide: Command Line Interface included with this release or the JavaTest harness online help for detailed instructions about using the command line to run tests and to modify the configuration.

Setting Configuration Values on the Command Line

If you intend to set one or more configuration values on the command line for a test run, then see the JavaTest Harness User’s Guide: Command-Line Interface, or the JavaTest harness online help for a detailed description.

You must use one of the following sources to identify the configuration question-tag names used in the command line:

- Question Log file: (`questionLognnnn.html`) generated by the Configuration Editor in `workdirectory/jtData`

- Config.html report: generated from the JavaTest harness GUI

- Question Tags: displayed in the Configuration Editor

See the JavaTest Harness User’s Guide: Graphical User Interface or the JavaTest harness online help for a detailed description of displaying the Question Tags in the Configuration Editor and generating reports containing the `config.html` file.

#### 4.1.2 JAXB-Specific Configuration Settings

A number of questions in the JavaTest harness configuration interview are generic and apply to most Java product TCK suites. This section describes configuration settings that are specific to the JAXB TCK.

The JAXB TCK 2.3 includes a special configuration interview used by the JavaTest harness to collect information from you about your test environment and to create the configuration used to run tests. The TCK configuration interview (TCK interview) consists of the following sections:

- Test Environment: the first section of the interview collects information about the test environment used to run the JAXB TCK 2.3 (such as the type of environment and the type of agent used).

- Schema Compiler Questions: the second section of the interview collects information about how to compile the source schema on your platform.

  - XML Validation Tests: optional tests that must be run if schema validation is performed using a mechanism other than JAXP.

- Schema Generator Questions: the third section of the interview collects information about how to generate XML schema from Java sources on your platform.

- How Tests are Run: the last section of the interview collects information on how the tests are run (such as Keywords and the Exclude List).

#### The Configuration Editor Questions

The table describes the Configuration Editor questions, lists the question tags and text, and gives examples of relevant answers to correctly configure the JavaTest harness to run the test suite.

Note | To view the question tags in the Configuration Editor, select View and then Question Tag in the editor menu.

Table 4-1 Configuration Editor Questions and Relevant Answers

Item Name | Question Tag and Text | Comments and Proposed Answers
--- | --- | ---
Welcome! | Tag: jck.prolog Welcome to the Configuration Editor for JAXB TCK testsuite! | None
Configuration Name | Tag: jck.env.envName Provide a short identifier that names the configuration you are creating. | This is a short string that identifies this particular configuration. Select a name that describes the configuration. Example: `jaxb_win32` The name must begin with a letter, followed by letters, digits, or an underscore, and must not contain a white space or punctuation characters.
Description | Tag: jck.env.description Provide a short description that identifies the configuration you are creating. | JavaTest uses this short description to provide more detail about the configuration, for example, in reports. This information might be useful to an auditor looking at the test run reports, and could include the version number of the product and the name of the tester. Example: `John Smith x86 Java Architecture for XML Binding 2.3`
Execution Mode | Tag: jck.env.testPlatform.multiJVM Specify whether you want to run the tests in SingleJVM or MultiJVM mode. Depending on the selected mode, you can configure to run the compiler either from the command line, or via the Java Compiler API, or via a custom class accessed by the core reflection API. | Answer `MultiJVM Mode` if the JavaTest harness can directly start your product, for example, from a command line in an MSDOS window or UNIX shell; this is the required mode for the JAXB TCK. Typically, applications that do not support such actions run in point-and-click environments or in browsers. For example, the JavaTest harness cannot start a new instance of a Java virtual machine inside a browser. If you answer MultiJVM Mode , then you need to answer additional interview questions to specify whether you plan to run the tests locally. In addition, you need to specify the details about the Java Virtual Machine in which the tests will run (the questions in the Runtime Other JVM section of this interview) and the details about the Java launcher.
Execute Locally | Tag: jck.env.testPlatform.local Will you run the TCK tests on the system that hosts the JavaTest harness? | If you plan to run the tests on the system on which you are running this interview, then the editor gathers configuration information directly from the system. For example, you will be able to browse the local file system to point to the required files.
Agent Type | Tag: jck.env.jaxb.agent.agentType The JavaTest Agent can be run in two modes: active and passive. Which mode do you wish to use? | Select the agent type you wish to use. If you want to use the passive agent, then two additional questions will appear asking you to specify the passive agent host and default agent port.
Passive Host | Tag: jck.env.jaxb.agent.agentPassiveHost What is the of the host on which you run the tests? | This is the name of the system on which the passive agent runs and executes tests. The name of the system must be accessible from the system on which JavaTest runs. Since the JavaTest agent is passive, you can only change the machine you specify here by running this interview again and changing the name of the passive host.
Default Agent Port | Tag: jck.env.jaxb.agent.useAgentPortDefault Do you wish to use the default port for the JavaTest harness to contact the JavaTest Agent? | By default, the JavaTest harness communicates with a passive agent using port 1908. You must change only the default if you are running more than one passive agent on a system; this might be the case if you have set up batch runs. If you answer `No`, then you will need to specify the default port number in the next interview question.
Passive Port | Tag: jck.env.jaxb.agent.agentPassivePort Which port does the JavaTest harness use to contact the JavaTest Agent? | Specify the port you want to use to communicate with the JavaTest agent.
Test Platform File Separator | Tag: jck.env.jaxb.agent.fileSeparator Which file separator character is used on the test platform? | Specify the appropriate file separator for your operating system. For example, for Windows, use the back slash (\) character. For Solaris OS or Linux operation system, use the forward slash (/) character.
Test Platform Path Separator | Tag: jck.env.jaxb.agent.pathSeparator Which path separator character is used on the test platform?. | Specify the appropriate path separator for your operating system. For example, on Windows systems, specify the ; character, on Unix systems specify the : character. Other platforms may differ.
Agent Map File | Tag: jck.env.jaxb.agent.mapArgs | Because JavaTest and the JavaTest agent run on different systems, values such as path names and variable names may differ on each system. For example, if a file is accessed over a network, it might be mounted as `H:\tests\lib` on the JavaTest system and as `F:\tests\lib` on the system running the JavaTest agent. The map file is used to associate values used on the JavaTest agent with those used by JavaTest. The map file is specified on the JavaTest agent, but the use of the map must be enabled here. For more information about map files, refer to the JavaTest User’s Guide or to the JavaTest online help.
Java Launcher | Tag: jck.env.jaxb.testExecute.cmdAsFile Enter the full path name of the Java launcher that runs the tests through the Java Compiler API interface. | This interview question appears only if you answered `Yes` to the Test Platform MultiJVM question of this interview. This is the command used on the reference system to invoke the Oracle reference Java. NOTE: Use the `java` command in JDK (not JRE). * On Solaris or Linux platforms, type:`$JAVA_HOME/bin/java` For example: `/usr/java/bin/java` * On Win32 systems, type: `%JAVA_HOME%\bin\java.exe` For example: “C:\Java\jdk–9\bin\java.exe” Ensure that you supply the full file name, including the file extension.
Other Options | Tag: jck.env.jaxb.testExecute.otherOpts Specify any additional commandline options that must be set. | Specify any command-line options that JavaTest should set for your compiler when it runs the tests on your system. Specify the options using `name=value` pairs. For example you may want to specify: `-Xmx256m -Xms128m` to change the default maximum and initial Java heap size. NOTE: If you use Java Launcher from JCK 8 to run the tests, specify the `-Djava.endorsed.dirs=<JAXB_HOME>/lib` option.
Other Environment Variables | Tag: jck.env.jaxb.testExecute.otherEnvVars Except for CLASSPATH, if there are any other environment variables that must be set for the reference Java launcher, enter them here. | Specify any environment variables that the JavaTest harness should use in the environment created to run the tests on your system. Specify the variables using the `name=value` pairs. For example, on Solaris systems: `special_path=/home/env/config` NOTE: You must specify both variables: JAVA_HOME and JAXB_HOME. For example, on Solaris: JAVA_HOME=/jdk-8/solarissparcv9 JAXB_HOME=/jaxb-2.3 on Windows: JAVA_HOME=d:\jdk-8\windows-i586 JAXB_HOME=d:\jaxb-2.3 Where the path to the directory of J2SE on Solaris should be specified in JAVA_HOME, JAXB_HOME points to the directory under which the bin/, docs/, examples/, and lib/ directories reside. The JavaTest cannot inherit environment variables from your operating system environment. If you find that your tests run correctly outside of the JavaTest harness, but do not run correctly using the JavaTest harness, then the reason might be that a value set in your operating system environment is not available to the test. If you check your operating system environment and determine that this is the case, then set the missing values here.
Need Extra JAXB Classes | Tag: jck.env.jaxb.classes.needJaxbClasses Do you need to specify extra JAXB classes for the Java launcher to execute tests? | The JAXB classes must be available (that is, can be found and loaded) during test execution. This means that JAXB JAR archives or directories which contain the JAXB classes must be in the test executing Java class path. Answer `No` if the JAXB JAR archives are in the Java default class path, for example, all jar files are stored in the jdk_install_dir/jre/lib/ext directory. Answer `Yes` if some directories or archives are located not in the Java default class path. If you answer `Yes`, then you will be asked to specify necessary class paths or JAXB archives.
Schema Compiler Questions | Tag: jck.env.jaxb.xsd_compiler.intro The following questions collect information about how to compile the source schema on your platform. | None.
Schema Compiler Operation Mode | Tag: jck.env.jaxb.xsd_compiler.defaultOperationMode Would you like to run your schema compiler in default operation mode? | A JAXB compatible implementation must support a default operating mode in which all the required XML Schema to Java bindings that are described in the JAXB specification must be implemented. Errors must be reported when alternative or extension non-required features are encountered. A JAXB compatible implementation may support non-default operating modes. These modes must support all the XML Schema to Java bindings that are described in JAXB specification, but may also generate alternative or extension bindings for XML Schema constructs, which are not required by this specification. If you select `Yes`, then the schema compiler is supposed to run in default operation mode and the tests for non-required features must be passed (as negative tests with expected error messages). If you select `No`, then the schema compiler is supposed to run in non-default operation mode and the tests for non-required features will not be run. For more information on default operation mode requirements, see the Compatibility section of the JAXB specification.
Optional XML Validation Tests | Tag: jck.env.jaxb.xsd_compiler.skipValidationOptional Is Schema Validation implemented via mechanism different from JAXP? | XML validation can be implemented from JAXP or from some other mechanism. If the validation is implemented from JAXP, then validation checking tests can be skipped by deselecting them in the test interview. If you use some other tools for schema validation, then XML validation tests are mandatory.
Schema Compiler Run Command | Tag: jck.env.jaxb.xsd_compiler.testCompile. xjcCmd The remaining questions ask which tests you want to run and how you want them to be run. | This is the command used to invoke your schema compiler. For example, for the Oracle JAXB implementation on Solaris we provide a script `TCKDIR/solaris/bin/ xjc.sh`, which compiles schemas into class files. The command is as follows: `/bin/ksh solaris/bin/xjc.sh` For the Oracle JAXB implementation on Windows, we provide a script TCKDIR `\win32\bin\xjc.bat`, which compiles schemas into class files. The command is as follows: `win32\bin\xjc.bat` The xjc script supports the following mandatory command-line options: `xjc -p <pkg> -d <dir> <schema files>` where: • `-p <pkg>` specifies the target package • `-d <dir>` specifies the directory to store generated files.
Schema Compiler Class | Tag: jaxb.xsd_compiler.run.compilerWrapperClass You must provide a custom class to invoke your compiler. This class should implement the com.sun.jaxb_tck.lib.SchemaCompilerTool interface. | When you run schema compilation through the JavaTest agent, your schema compiler will be executed in the agent’s JVM. Your implementation must provide a custom class to invoke your schema compilation tool. This class should implement the `SchemaCompilerTool` interface: `package com.sun.jaxb_tck.lib; public interface SchemaCompilerTool { /** * @param xsdFiles – array of strings containing schema files * @param packageName – the target package * @param outDir – output directory where java file(s) will be generated * @param out - output stream for logging * @param err - error stream for logging * @return 0 if java file(s) generated successfully */ int compile(String[] xsdFiles, String packageName, File outDir, PrintStream out, PrintStream err); }` Schema compilation should be accomplished during invocation of compile method. The JAXB TCK includes the following class that is fully compatible with Oracle’s reference implementation and that can be used for schema compilation: `com.sun.jaxb_tck.lib.SchemaCompiler.` The realization of the method `compile(String[] xsdFiles, String packageName, File outDir, PrintStream out, PrintStream err)` compiles a schema into `java` sources. If your implementation doesn’t provide such a class, then create it and specify it here.
Schema Generator Questions | Tag: jck.env.jaxb.schemagen.intro The following questions collect information about how to generate xml schema from java sources on your platform. | None.
Schema Generator Presence | Tag: jck.env.jaxb.schemagen.skipJ2XOptional Does your implementation provide schema generator which is able to generate schemas from Java sources? | Java Architecture for XML Binding 2.3 specification does not require any implementation, which provides a possibility to generate the schemas from the java sources. If they are provided, then all specification requirements should be met.
Schema Generator Run Command | Tag: jck.env.jaxb.schemagen.run.jxcCmd Enter the command to run the schema generator. | This is the command used to invoke your schema generator. For example, for the Oracle JAXB implementation on Solaris we provide a script `TCKDIR/ solaris/bin/schemagen.sh`, which generates the schemas from the java files. The command is: `/bin/ksh solaris/bin/schemagen.sh` For the Oracle JAXB implementation on Windows, we provide a script `TCKDIR \win32\bin\schemagen.bat`, which compiles the schemas into class files. The command is: `win32\bin\schemagen.bat` The schemagen script supports the following mandatory command-line options: `schemagen -d <dir> <java files>`, where, `-d <dir>` specifies the directory to store the generated files.
Schema Generator Class | Tag: jck.env.jaxb.schemagen.run.schemagenWrapperClass You must provide a custom class to invoke your schema generator. This class should implement the com.sun.jaxb_tck.lib.SchemaGenTool interface. | When you run schema generation through JavaTest agent, your schema generator will be executed in the agent’s JVM. Your implementation must provide a custom class to invoke your schema generation tool. This class should implement the SchemaGenTool interface: `package com.sun.jaxb_tck.lib; public interface SchemaGenTool { /** * @param javaFiles - array of strings containing java files * @param outDir - output directory where schema file(s) will be generated * @param out – output stream for logging * @param err – error stream for logging * @return 0 if schema file(s) generated successfully */ int generate(String[] javaFiles, File outDir, PrintStream out, PrintStream err); }` Schema generations should be complete during the invocation of the generate method. The JAXB TCK includes the following class that is fully compatible with Oracle’s reference implementation and that can be used for schema generation: `com.sun.jaxb_tck.lib.SchemaGen`. The realization of the method `generate(String[] javaFiles, File outDir, PrintStream out, PrintStream err)` generates the XML schemas from the `java` files. If your implementation doesn’t provide such a class, then create it and specify it here.
Schema Compiler Questions | Tag: jck.env.jaxb.xsd_compiler.intro The following questions collect information about how to compile the source schema on your platform. | None.
Standard Values | Tag: jck.parameters The remaining questions ask which tests you want to run and how you want them to be run. | None.
Specify an Exclude List? | Tag: jck.excludeList.needExcludeList Do you wish to specify an exclude list? | Answer `Yes` if you want to specify an exclude list for the test run. If you select Yes, then select the location of the exclude list to use. Answer `No` if you want to run all tests that are not filtered out by other run filters.
Which Exclude List? | Tag: jck.excludeList.excludeListType Which exclude list do you wish to use? | This question appears only if you answered Yes to the previous configuration interview question. Select either the Initial option to use the exclude list provided with the test suite or the Specify option to specify the exclude list you wish to use.
Specify Exclude List Files | Tag: jck.excludeList.customFiles Specify the files that make up the exclude list you wish to use. | Click Add to activate a file chooser with which you select an exclude list file. Exclude list files conventionally use the extension ``.jtx`.
Specify Keywords? | Tag: jck.keywords.needKeywords Do you wish to specify a keyword expression to select/reject tests based on keywords contained in each test description? | Keywords are tokens associated with specific tests. Answer `Yes` to run tests based on the keyword and the other run filter settings. If you select Yes, then you are asked to specify the keyword to use. Answer `No` to run all tests that are not filtered out by other run filters.
Specify Status? | Tag: jck.priorStatus.needStatus Do you wish to select tests to run based on their result in a previous run? | Answer Yes to run tests based on the status from the previous test run and the other run filter settings. If you select Yes, then you are asked for the status or statuses. Answer No to run all tests that are not filtered out by other run filters.
Concurrency | Tag: jck.concurrency.concurrency The JavaTest harness can run tests concurrently. Specify the maximum number of tests that should be run concurrently: | The JavaTest harness can run tests concurrently. If you are running the tests on a multiprocessor computer, then the concurrency can accelerate your test runs. The default range of values that the JavaTest harness uses is from 1 to 50. For the first test run, keep this value set to 1.
Time Factor | Tag: jck.timeout.timeout Specify a time factor that is applied to each test’s default timeout. For example, specifying 2 doubles the time for each test (the default is 1): | The default 1.0 corresponds to 10 minutes. Use the floating point format specific to your locale. NOTE: Setting a proper time factor value requires consideration of such technical factors as the network connector speed.
Completed! | Tag: jck.end Congratulations! This completes the configuration. Click Done to save your answers and close the editor. To run the test suite, choose Run Tests→Start. | None.

### 4.2 Unused Section

### 4.3 Unused Section

### 4.4 Custom Configuration Handlers

Configuration handlers are used to configure and unconfigure a JAXB 2.3 implementation during the certification process. These are similar to deployment handlers but used for configuration. A configuration handler is an Ant build file that contains at least the required targets listed below: * `config.vi` - to configure the vendor implementation * `clean.vi` - to unconfigure the vendor implementation

These targets are called from the `<TS_HOME>/bin/build.xml` file and call down into the implementation-specific configuration handlers.

To provide your own configuration handler, create a config.vi.xml file with the necessary configuration steps for your implementation and place the file under the `<TS_HOME>/bin/xml/impl/<your_impl>` directory.

For more information, see `<TS_HOME>/bin/xml/impl/glassfish/config.vi.xml`, the configuration file for the Java EE 8 RI.

### 4.5 Custom Deployment Handlers

Deployment handlers are used to deploy and undeploy the WAR files that contain the tests to be run during the certification process. A deployment handler is an Ant build file that contains at least the required targets listed in the table below.

The JAXB TCK provides these deployment handlers: * `<TS_HOME>/bin/xml/impl/none/deploy.xml` * `<TS_HOME>/bin/xml/impl/glassfish/deploy.xml`

The `deploy.xml` files in each of these directories are used to control deployment to a specific container (no deployment, deployment to the GlassFish Web container, deployment to the Tomcat Web container) denoted by the name of the directory in which each `deploy.xml` file resides. The primary `build.xml` file in the `<TS_HOME>/bin` directory has a target to invoke any of the required targets (-deploy, -undeploy, -deploy.all, -undeploy.all).

#### 4.5.1 To Create a Custom Deployment Handler

To deploy tests to another JAXB implementation, you must create a custom handler. 1. Create a new directory in the <TS_HOME>/bin/impl directory tree. For example, create the <TS_HOME>/bin/impl/my_deployment_handler directory. Replace my_deployment_handler with the value of the impl.vi property that you set in Step 5 of the configuration procedure described in Section 4.2, "Configuring Your Environment to Repackage and Run the TCK Against the Vendor Implementation".

1. Copy the deploy.xml file from the <TS_HOME>/bin/xml/impl/none directory to the directory that you created.

2. Modify the required targets in the deploy.xml file. This is what the deploy.xml file for the "none" deployment handler looks like.

       <project name="No-op Deployment" default="deploy">
           <!-- No-op deployment target -->
           <target name="-deploy">
               <echo message="No deploy target implemented for this deliverable"/>
           </target>
           <target name="-undeploy">
               <echo message="No undeploy target implemented for this deliverable"/>
           </target>
           <target name="-deploy.all">
               <echo message="No deploy target implemented for this deliverable"/>
           </target>
           <target name="-undeploy.all">
               <echo message="No undeploy target implemented for this deliverable"/>
           </target>
       </project>

   Although this example just echoes messages, it does include the four required Ant targets (-deploy, -undeploy, -deploy.all, -undeploy.all) that your custom deploy.xml file must contain. With this as your starting point, look at the required targets in the deploy.xml files in the tomcat and glassfish directories for guidance as you create the same targets for the Web container in which you will run your implementation of JAXB.

The following Ant targets can be called from anywhere under the <TS_HOME>/src directory:

- `deploy`

- `undeploy`

- `deploy.all`

- `undeploy.all`

The deploy.all and undeploy.all targets can also be called from the <TS_HOME>/bin directory.

Note | The targets in the deploy.xml file are never called directly. They are called indirectly by the targets listed above.

### 4.6 Using the JavaTest Harness Software

There are two general ways to run the JAXB TCK test suite using the JavaTest harness software:

- Through the JavaTest GUI; if using this method, please continue on to Section 4.7, "Using the JavaTest Harness Configuration GUI."

- In JavaTest batch mode, from the command line in your shell environment; if using this method, please proceed directly to Chapter 5, "Executing Tests."

### 4.7 Using the JavaTest Harness Configuration GUI

You can use the JavaTest harness GUI to modify general test settings and to quickly get started with the default JAXB TCK test environment. This section covers the following topics:

- Configuration GUI Overview

- Starting the Configuration GUI

- To Configure the JavaTest Harness to Run the JAXB TCK Tests

- Modifying the Default Test Configuration

Note | It is only necessary to proceed with this section if you want to run the JavaTest harness in GUI mode. If you plan to run the JavaTest harness in command-line mode, skip the remainder of this chapter, and continue with Chapter 5, "Executing Tests."

#### 4.7.1 Configuration GUI Overview

In order for the JavaTest harness to execute the test suite, it requires information about how your computing environment is configured. The JavaTest harness requires two types of configuration information:

- Test environment: This is data used by the tests. For example, the path to the Java runtime, how to start the product being tested, network resources, and other information required by the tests in order to run. This information does not change frequently and usually stays constant from test run to test run.

- Test parameters: This is information used by the JavaTest harness to run the tests. Test parameters are values used by the JavaTest harness that determine which tests in the test suite are run, how the tests should be run, and where the test reports are stored. This information often changes from test run to test run.

The first time you run the JavaTest harness software, you are asked to specify the test suite and work directory that you want to use. (These parameters can be changed later from within the JavaTest harness GUI.)

Once the JavaTest harness GUI is displayed, whenever you choose Start, then Run Tests to begin a test run, the JavaTest harness determines whether all of the required configuration information has been supplied:

- If the test environment and parameters have been completely configured, the test run starts immediately.

- If any required configuration information is missing, the configuration editor displays a series of questions asking you the necessary information. This is called the configuration interview. When you have entered the configuration data, you are asked if you wish to proceed with running the test.

#### 4.7.2 Starting the Configuration GUI

Before you start the JavaTest harness software, you must have a valid test suite and Java SE 8 installed on your system.

The JAXB TCK includes an Ant script that is used to execute the JavaTest harness from the `<TS_HOME>` directory. Using this Ant script to start the JavaTest harness is part of the procedure described in Section 4.7.3, "To Configure the JavaTest Harness to Run the TCK Tests."

When you execute the JavaTest harness software for the first time, the JavaTest harness displays a Welcome dialog box that guides you through the initial startup configuration.

- If it is able to open a test suite, the JavaTest harness displays a Welcome to JavaTest dialog box that guides you through the process of either opening an existing work directory or creating a new work directory as described in the JavaTest online help.

- If the JavaTest harness is unable to open a test suite, it displays a Welcome to JavaTest dialog box that guides you through the process of opening both a test suite and a work directory as described in the JavaTest documentation.

After you specify a work directory, you can use the Test Manager to configure and run tests as described in Section 4.7.3, "To Configure the JavaTest Harness to Run the TCK Tests."

#### 4.7.3 To Configure the JavaTest Harness to Run the TCK Tests

The answers you give to some of the configuration interview questions are specific to your site. For example, the name of the host on which the JavaTest harness is running. Other configuration parameters can be set however you wish. For example, where you want test report files to be stored.

Note that you only need to complete all these steps the first time you start the JavaTest test harness. After you complete these steps, you can either run all of the tests by completing the steps in Section 5.1, "Starting JavaTest," or run a subset of the tests by completing the steps in Section 5.2, "Running a Subset of the Tests."

1. Change to the `<TS_HOME>/bin` directory and start the JavaTest test harness:
   `cd <TS_HOME>/bin`
   `ant gui`

2. From the File menu, click Open Quick Start Wizard.
   The Welcome screen displays.

3. Select Start a new test run, and then click Next.
   You are prompted to create a new configuration or use a configuration template.

4. Select Create a new configuration, and then click Next.
   You are prompted to select a test suite.

5. Accept the default suite (`<TS_HOME>/src`), and then click Next.
   You are prompted to specify a work directory to use to store your test results.

6. Type a work directory name or use the Browse button to select a work directory, and then click Next.
   You are prompted to start the configuration editor or start a test run. At this point, the JAXB TCK is configured to run the default test suite.

7. Deselect the Start the configuration editor option, and then click Finish.

8. Click Run Tests, then click Start.
   The JavaTest harness starts running the tests.

9. To reconfigure the JavaTest test harness, do one of the following:

   - Click Configuration, then click New Configuration.

   - Click Configuration, then click Change Configuration.

10. Click Report, and then click Create Report.

11. Specify the directory in which the JavaTest test harness will write the report, and then click OK.
    A report is created, and you are asked whether you want to view it.

12. Click Yes to view the report.

#### 4.7.4 Modifying the Default Test Configuration

The JavaTest GUI enables you to configure numerous test options. These options are divided into two general dialog box groups:

- Group 1: Available from the JavaTest Configure/Change Configuration submenus, the following options are displayed in a tabbed dialog box:

  - Tests to Run

  - Exclude List

  - Keywords

  - Prior Status

  - Test Environment

  - Concurrency

  - Timeout Factor

- Group 2: Available from the JavaTest Configure/Change Configuration/Other Values submenu, or by pressing Ctrl+E, the following options are displayed in a paged dialog box:

  - Environment Files

  - Test Environment

  - Specify Tests to Run

  - Specify an Exclude List

Note that there is some overlap between the functions in these two dialog boxes; for those functions use the dialog box that is most convenient for you. Please refer to the JavaTest Harness documentation or the online help for complete information about these various options.

Copyright © 2018, Oracle and/or its affiliates. All rights reserved.