|
|
| Line 1: |
Line 1: |
| − | Session tests in Eclipse are tests that require that a new Eclipse session
| + | =Business Intelligence and Reporting Tools (BIRT) Project Wiki= |
| − | be launched for every test case run. Thus, they have additional requirements
| + | |
| − | regarding controling the environment test cases are run (VM, set of plug-ins
| + | |
| − | available, configuration, instance location, command line parameters) and
| + | |
| − | how results are communicated back to the test runner. This FAQ-like document describes
| + | |
| − | how the Platform/Core implemented support for running session tests in the
| + | |
| − | hopes of encouraging adoption of this framework not only by all the Platform/Core
| + | |
| − | team members but also by members of other Eclipse teams interested in developing
| + | |
| − | their own session tests.
| + | |
| | | | |
| − | <ol>
| + | '''Introduction''' |
| − | <li>
| + | |
| − | <p><strong>What is a session test?</strong></p>
| + | |
| − | <p>It is a test case that needs to be run isolated in a separate VM instance.
| + | |
| − | Technical details: The VM running a set of test cases (the <em>controller
| + | |
| − | VM</em>) will spawn a second instance (the <em>target VM</em>) for each
| + | |
| − | session test case to be run. The test results are collected (by using a
| + | |
| − | socket) and presented to the test runner as if the test had run in the same
| + | |
| − | VM.</p>
| + | |
| | | | |
| − | </li>
| + | This section of the BIRT Wiki contains a description of proposed functionality for future releases. The contents are organized by major projects. Each project is assigned a BIRT Project Specification (BPS) number and a name. Each BPS may have one or more features associated with it and may resolve one or more Bugzilla requests from the community. |
| − | <li>
| + | |
| − | <p><strong>Where can I get the framework?</strong></p>
| + | |
| − | <p> Check out the <code>org.eclipse.core.tests.harness</code> project from
| + | |
| − | dev.eclipse.org. The infrastructure for session tests is in the <code>org.eclipse.core.tests.session</code>
| + | |
| − | package. It does not hurt mentioning that besides requiring this plug-in,
| + | |
| − | you should have <code>org.junit</code> as a pre-requisite as well.</p>
| + | |
| | | | |
| − | </li>
| + | A short, requirement-level description is given for each BPS, followed by a link to one or more pdf documents that describe the behavior of the proposed functionality in detail. The community is invited to give feedback on a particular BPS by using the Wiki comments capability for the associated page. This feedback can be as simple as a reinforcing "vote" on the importance of the capability or a more specific request for changes in the proposed behavior. The BIRT team will read and respond to the feedback, and then update the associated BPS as appropriate. |
| − | <li>
| + | |
| − | <p><strong>What it is the easiest way to transform my regular plug-in tests
| + | |
| − | into session tests?</strong></p>
| + | |
| − | <p> Change the test suite creation to use <code>org.eclipse.core.tests.session.SessionTestSuite</code>
| + | |
| − | instead of <code>junit.framework.TestSuite</code>. Like this:</p>
| + | |
| − | <p>Before:</p>
| + | |
| | | | |
| − | <pre>
| + | When entering comments, we would appreciate it if you would put an obfuscated version of your e-mail address in the author field, like this: |
| − | public class MyTestCase extends TestCase {
| + | |
| − | ...
| + | |
| − | public void test1() {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | public static Test suite() {
| + | |
| − | return new TestSuite(MyTestCase.class);
| + | |
| − | }
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>After:</p>
| + | |
| − | <pre>
| + | |
| − | public class MyTestCase extends TestCase {
| + | |
| − | ...
| + | |
| − | public void test1() {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | public static Test suite() {
| + | |
| − | return new SessionTestSuite("org.myplugin.tests", MyTestCase.class);
| + | |
| − | }
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>The plug-in id is necessary so the plug-in which the class containing the
| + | |
| − | test case should be loaded from can be determined. Note hat it is possible
| + | |
| − | to build an empty suite and then manually add test cases and/or test suites.
| + | |
| − | When running your tests again, every test case in the suite (included those
| + | |
| − | in nested test suites) will be run in a separate Eclipse session. Note also
| + | |
| − | that if a session test suite contains another session test suite (or any
| + | |
| − | other special types of test suite), the outer session test suite will rule.</p>
| + | |
| − | </li>
| + | |
| − | <li><strong>Why do I get a <em>"...SetupException: No setup descriptions
| + | |
| − | found. Ensure you are specifying the path for an existing setup file...</em>"?</strong>
| + | |
| − | <p> You are running your session test suite as a regular <em>JUnit test</em>
| + | |
| − | instead of as a <em>Plug-in JUnit test</em>. A default setup (in other words,
| + | |
| − | command line) for launching new Eclipse sessions when running session tests
| + | |
| − | can be computed when running the test suite as a plug-in test, so no further
| + | |
| − | configuration is necessary. It basically contains the same parameters as
| + | |
| − | the ones used to launch the controller instance, with a different instance
| + | |
| − | location (the -data parameter). When launching the controller instance as
| + | |
| − | a regular JUnit test suite, the setup for running session tests has to be
| + | |
| − | configured manually. The framework looks for a <code>default-setup.xml</code>
| + | |
| − | file in the current directory, but a different file name and location can
| + | |
| − | be specified by using the <code>setup.file</code> system property. If not
| + | |
| − | running in Eclipse, and no setup file can be found, the execution fails
| + | |
| − | with this exception. See also next FAQ.</p>
| + | |
| | | | |
| − | </li>
| + | '''user at example dot com''' |
| − | <li>
| + | |
| − | <p><strong>Should I run my tests using a JUnit or PDE Junit launch configuration?</strong></p>
| + | |
| − | <p>Running with a PDE Junit launch configuration will allow you to test code
| + | |
| − | in your workspace. Also, launching with PDE JUnit frees you from having
| + | |
| − | to provide configuration parameters, since reasonable defaults will be obtained
| + | |
| − | from the controlling Eclipse. If you are still interested in running your
| + | |
| − | tests as a JUnit launch configuration, see the next FAQ.</p>
| + | |
| − | </li>
| + | |
| − | <li>
| + | |
| − | <p><strong>How do I run session tests from a JUnit (not PDE JUnit) launch
| + | |
| − | configuration?</strong> </p>
| + | |
| − | <p>Ensure you provide a valid set of setup files. Setup files describe option
| + | |
| − | sets that can be used when launching Eclipse. See question about options
| + | |
| − | supported by the framework.</p>
| + | |
| − | </li>
| + | |
| − | <li>
| + | |
| − | <p><strong>How do I run UI-oriented tests?</strong> </p>
| + | |
| − | <p>Make sure you also set the application when launching the target instance
| + | |
| − | to be <code>SessionTestSuite.UI_TEST_APPLICATION</code>:</p>
| + | |
| − | <pre>SessionTestSuite suite = new SessionTestSuite("org.myplugin.tests", MyTestCase.class);
| + | |
| − | suite.setApplicationId(SessionTestSuite.UI_TEST_APPLICATION);</pre>
| + | |
| − | </li>
| + | |
| | | | |
| − | <li><strong>How can I see the command-line used for the Eclipse instance where my session test runs?</strong>
| + | so that we may follow up with you if we have questions about your comment. |
| − | <p>Use the <code>setup.debug</code> boolean system property (check the question about supported options).</p>
| + | |
| − | </li>
| + | |
| − | <li><strong>How do I debug a failing test case?</strong>
| + | |
| − | <p><strong>The easy way:</strong> run the failing test case in isolation as
| + | |
| − | a regular JUnit plug-in test. Ensure the command-line matches the one built
| + | |
| − | by the session test framework when running it as a session test.</p>
| + | |
| | | | |
| − | <p><strong>The hard way:</strong> you can configure the session test to launch the target VM in debug mode using the following
| + | The Projects listed cover functionallity existing in the 2.0 realease as well as features planned for future releases. |
| − | VM argument:</p>
| + | |
| − | <tt>-Dsetup.override.vmArgs=Xdebug;Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y</tt>
| + | |
| − | <p>If you are using the setup.files mechanism (see below), then use these VM arguments intead:</p>
| + | |
| − | <tt>-Dsetup.files=default-setup.xml -Dsetup.options=remote_debug</tt>
| + | |
| − | <p>When the target VM is launched in debug mode, you must connect the debugger to each test individually:
| + | |
| − | <ol>
| + | |
| − | <li>From the "Run" menu, select "Debug..."</li>
| + | |
| − | <li>Select the "Remote Java Application" category on the left hand side</li>
| + | |
| − | <li>Click the "New" button to create a new launch configuration</li>
| + | |
| − | <li>Leave all settings as default and click "Debug"</li>
| + | |
| − | </ol></p>
| + | |
| − | </li>
| + | |
| − | <li><strong>How do I run performance session tests?</strong>
| + | |
| − | <p>Use the <code>PerformanceSessionTestSuite</code> instead.</p>
| + | |
| − | </li>
| + | |
| − | <li><strong>How do I run session tests that have private instance locations?</strong>
| + | |
| − | <p>Use the <code>WorkspaceSessionTestSuite</code> instead. Every test suite
| + | |
| − | has its own instance location (workspace), all test cases are run on separate
| + | |
| − | sessions on the same workspace. After the last test case is run, that location
| + | |
| − | is deleted.</p>
| + | |
| − | </li>
| + | |
| − | <li><strong>I just want to try out some examples. Any pointers?</strong>
| + | |
| − | <p>The <code>org.eclipse.core.tests.session.samples</code> package has some
| + | |
| − | examples. If you load the org.eclipse.core.tests.runtime and org.eclipse.core.tests.resources
| + | |
| − | projects, you will find real-world examples of how to use this framework.
| + | |
| − | Just look for the subclasses of <code>SessionTestSuite</code>.</p>
| + | |
| | | | |
| − | </li>
| + | If you are interested in proposing another project that does not appear on the list, please send your suggestions to the BIRT PMC. |
| − | <li><strong>What are all supported options and how to use them?</strong>
| + | |
| − | <p>The options for the session test framework are specified in the form of
| + | |
| − | system properties. <em>You only have to use these options if running with
| + | |
| − | the default settings (the currently target JRE and Eclipse and default command
| + | |
| − | line options) are not appropriate.</em></p>
| + | |
| − | <ul>
| + | |
| − | <li><strong>setup.options</strong> - only valid when setup files are available.
| + | |
| − | Setup files describe option sets, which are collections of command-line
| + | |
| − | options that can be used while running Eclipse. Examples:
| + | |
| − | <p><code>-Dsetup.options=sun_1.5,eclipse_3.1_M1,big_memory</code></p>
| + | |
| − | <p>would run Eclipse 3.1 M1 using Sun JRE 1.5 with whatever amount of
| + | |
| − | memory the <code>big_memory</code> option set specifies. While:</p>
| + | |
| | | | |
| − | <p><code>-Dsetup.options=ibm_1.4,eclipse_3.0,no_jit</code></p>
| + | Help us make BIRT the best it can be by providing feedback early and often! |
| − | <p>would run Eclipse 3.0 on IBM JRE 1.4 with Just-in-Time compilation
| + | |
| − | disabled</p>
| + | |
| − | <p>The meaning of every option set must be specified in setup files (see
| + | |
| − | below).</p>
| + | |
| − | </li>
| + | |
| − | <li><strong>setup.files</strong> - setup files provide option set definitions
| + | |
| − | for running the session tests. Setup files can be chained, so a more general
| + | |
| − | setup file (used by the whole team) can be customized with a user specific
| + | |
| − | setup file. This is useful since option sets must specify file system
| + | |
| − | locations, and every user has its own layout for JRE and Eclipse installs.
| + | |
| − | The expected use of this option is:
| + | |
| − | <p><code>-Dsetup.files=/tmp/default-setup.xml,~/user-setup.xml</code></p>
| + | |
| | | | |
| − | <p>Here, the <code>default-setup.xml</code> file is shared by the whole
| + | Thank you. |
| − | team and defines all option sets that the team may use. The <code>user-setup.xml</code>
| + | |
| − | merely overrides location sensitive options to adapt them to the user
| + | |
| − | specific file system layout. Look [http://eclipse.org/eclipse/platform-core/documents/default-setup.xml here]
| + | |
| − | for an example of a default setup file and [http://http://eclipse.org/eclipse/platform-core/documents/user-setup.xml here] for an example of a user custom setup file. These examples are intended
| + | |
| − | to be self-explanatory and are actually useful as they are (the user-specifc
| + | |
| − | setup file has to be tweaked to support your specific file system layout.</p>
| + | |
| − | </li>
| + | |
| | | | |
| − | <li><strong>setup.override.eclipseArgs</strong> - allows the user to manually
| + | --BIRT PMC |
| − | override command-line options corresponding to Eclipse arguments. Example:
| + | |
| − | <p><code>-Dsetup.override.eclipseArgs=data=c:/workspace;debug;showlocation</code></p>
| + | |
| − | </li>
| + | |
| − | <li><strong>setup.override.vmArgs</strong> - allows the user to manually
| + | |
| − | override command-line options corresponding to VM arguments (other than
| + | |
| − | system properties). Example:
| + | |
| − | <p><code>-Dsetup.override.vmArgs=Xint;Xmx256m;hotspot;cp=startup.jar</code></p>
| + | |
| − | </li>
| + | |
| − | <li><strong>setup.override.systemProperties</strong> - allows the user to
| + | |
| − | manually override command-line options corresponding to system properties.
| + | |
| − | Example:
| + | |
| − | <p><code>-Dsetup.override.systemProperties=osgi.checkConfiguration;osgi.locking=none</code></p>
| + | |
| | | | |
| − | </li>
| + | '''Proposed Projects''' |
| − | <li><strong>setup.debug</strong> - enables the session test framework debug
| + | |
| − | mode. In this mode, among other things, the command-line for every session
| + | |
| − | launched is dumped to the console, so it is useful to verify which option
| + | |
| − | sets are being selected and how they map to the command line.</li>
| + | |
| − | </ul>
| + | |
| − | <p></p>
| + | |
| − | </li>
| + | |
| − | <li><strong>What if I find problems using the session test framework or would
| + | |
| − | like to request/propose an enhancement?</strong>
| + | |
| − | <p>Please report them in Bugzilla against the Platform/Runtime component.</p>
| + | |
| | | | |
| − | </li>
| + | * [[BPS1]]: Crosstab Report Item |
| − | </ol>
| + | * [[BPS2]]: Multi-pass Aggregate, Sorting and Filtering |
| | + | * [[BPS3]]: Enable binding Binary/Clob data to report controls |
| | + | * [[BPS4]]: BIRT Java Script Objects |
| | + | * [[BPS5]]: Interactive Report Viewer |
| | + | * [[BPS6]]: Report Engine Scalability and Performance |
| | + | * [[BPS7]]: Data Engine Scalability and Performance |
| | + | * [[BPS8]]: Report Document |
| | + | * [[BPS9]]: Report Template |
| | + | * [[BPS10]]: BIRT Library |
| | + | * [[BPS11]]: BIRT Style and CSS Style Sheet |
| | + | * [[BPS12]]: Code Editor for BIRT Scripting |
| | + | * [[BPS13]]: Ad Hoc Parameters |
| | + | * [[BPS14]]: Dynamic Parameter Selection List |
| | + | * [[BPS15]]: Chart Builder and Wizard |
| | + | * [[BPS16]]: Property Editor for Chart Report Item |
| | + | * [[BPS17]]: Chart Components |
| | + | * [[BPS18]]: Chart Scripting |
| | + | * [[BPS19]]: Report Paging |
| | + | * [[BPS20]]: Expression Builder |
| | + | * [[BPS21]]: Report PDF Emitter |
| | + | * [[BPS22]]: Page-on-Demand Report Viewing |
| | + | * [[BPS23]]: XML Data Sources |
| | + | * [[BPS24]]: Dataset Output Parameters |
| | + | * [[BPS25]]: Visual SQL Query Builder |
| | + | * [[BPS26]]: SQL Editor |
| | + | * [[BPS27]]: BIRT Deployment |
| | + | * [[BPS28]]: Report Layout Manager |
| | + | * [[BPS29]]: Report Object Model API |
| | + | * [[BPS30]]: ODA Framework Migration to DTP |
| | + | * [[BPS31]]: ODA Runtime Driver Creation Wizard |
| | + | * [[BPS32]]: Export Report Data |
| | + | * [[BPS33]]: Searching in a Report |
| | + | * [[BPS34]]: Reportlet |
| | + | * [[BPS35]]: Pass-through of External Context Objects to ODA Data Providers |
| | + | * [[BPS36]]: Chart Model |
| | + | * [[BPS37]]: Chart Interactivity |
| | + | * [[BPS38]]: Chart Types |
| | + | * [[BPS39]]: Chart Engine API |
| | + | * [[BPS40]]: ODA Data Source Binding to BIRT Report |
This section of the BIRT Wiki contains a description of proposed functionality for future releases. The contents are organized by major projects. Each project is assigned a BIRT Project Specification (BPS) number and a name. Each BPS may have one or more features associated with it and may resolve one or more Bugzilla requests from the community.
A short, requirement-level description is given for each BPS, followed by a link to one or more pdf documents that describe the behavior of the proposed functionality in detail. The community is invited to give feedback on a particular BPS by using the Wiki comments capability for the associated page. This feedback can be as simple as a reinforcing "vote" on the importance of the capability or a more specific request for changes in the proposed behavior. The BIRT team will read and respond to the feedback, and then update the associated BPS as appropriate.
When entering comments, we would appreciate it if you would put an obfuscated version of your e-mail address in the author field, like this:
The Projects listed cover functionallity existing in the 2.0 realease as well as features planned for future releases.
If you are interested in proposing another project that does not appear on the list, please send your suggestions to the BIRT PMC.
