2022-10-20T11:08:26Z

2021-12-08T09:43:54Z

Sr: /* Custom Test Cases */

= Automatic Report Generation =

Expecco can generate reports in a number of formats: as human readable PDF or HTML documents, or as machine readable XML-, CSV- or plain text containing all relevant information on the test execution. XML reports are further provided in 3 different formats: Junit compatible, Nunit compatible and the full detail XML.

The full detail XML contains all data as collected during the run, including timestamps and input-/output values of every logged activity. By using XML and a processor such as XSLT, any custom report can be generated from it, if the other reports are not sufficient.

In addition, you can also save an ".elf" file (which stands for "''expecco log file''").
This can later be reopened with expecco, to present the same view as after the run (i.e. the whole hierarchical execution trace is shown). Then, the test can be reexecuted or additional reports can be generated (possibly with different detail settings).

== Report Templates ==
Report templates are used to specify the content and layout of created human readable reports. By default the so called "''Default Report Template''" is used, which is remembered in your user settings.
Other report templates can be created as tree elements and stored in the testsuite. They will be saved together with the testsuite.

The "''Default Report Template''" is stored in your settings file and thus private, whereas attached report templates are contained in the saved test suite file, and thus automatically available to everyone who gets the testsuite.

== How to create a report ==
[[Bild:Report Settings.png|thumb|200px|Report Settings]]
To create a report, a test has to be executed first (or a ".elf" file be loaded from a previous run).
This can be either a single block test or a whole testplan. After the execution is finished, click on the "''Print report''" button ([[Bild:Icon Print Report.png|Report button]]) causing a dialog to open.

Select the output format (PDF, HTML, XML, CSV or TEXT), the report language, a paper format and a template for the report. This template can be the default report template, a template from the current testsuite or a template which is stored separately in a file. You can also make ad-hoc changes to the printed report right before it is generated, by clicking on "''Edit Default Report Template''" in the 'Generate Report' dialog. There, you can specify the detail and the look of the report (depth, detail, filter, company, logos, colours, fonts, etc.).

Choose the format of the file(s) to be generated; you may select multiple output formats here.

Human readable formats are:
* '''PDF''' - for printable document
* '''HTML''' - to publish as an intranet or public web page
Machine readable formats are:
* '''XML''' - contains full detail
* '''jUnit''' - jUnit compatible XML (1)
* '''nUnit''' - nUnit compatible XML (2)
* '''CSV''' - to be imported into excel or word
* '''Text''' - plain text (3)

If the "''Open Preview''" box is checked, the generated reports are shown in a preview application. Otherwise, they are silently generated in the folder as specified in your report settings.

Now click on "''Generate Report''" in the 'Generate Report' dialog,
(with the "''Open Preview''" checked, to see the output).

Notes: 
(1) the jUnit format is compatible to the output generated by corresponding Java unit testing frameworks. The jUnit format is documented in [https://github.com/windyroad/JUnit-Schema/blob/master/JUnit.xsd "https ://github.com/windyroad/JUnit-Schema/blob/master/JUnit.xsd"]. These files can be imported by eg. Jenkins to generate trend- and statistic reports. For how to integrate expecco into Jenkins, see [https://doc.expecco.de/wiki2.x/Starting_expecco_via_Command_Line/en#Integration_with_Jenkins "Integration with Jenkins"] in the doc-Wiki.

(2) the nUnit format is compatible to the output generated by corresponding .NET unit testing frameworks.

(3) this simple format may be useful if the test result is to be sent as email or as an instant message (eg. Jabber)

== How to Add a Report Template to the Tree ==
It is a good idea to add templates to the project's tree. Often users wish to generate both a full-detail report for developers and a summary report for the management. Also, quality reports for final test before delivery usually provide less detail and may be signed with a barcode or QR tag (which can be generated by expecco and placed into a PDF, for example).

In the tree, select "''New Report Template''", give it a reasonable name, and modify its settings.
For a summary report, you will usually set a limit on the depth (i.e. not showing sub activities) and not showing pin values. You may also set a filter, to only present values or actions with a particular tag.

== Importing Report Templates ==
You can also put a number of report templates into a separate import library, to ensure that all test suites use a common (corporate identity conform) layout and detail.

== How to Customize a Report Template ==
To customize a report template, select it in the navigation tree. The same editor is used as when modifying the default report template.

=== Filter Settings ===
[[Bild:Report Filter Settings.png|thumb|200px|Filter Settings]]
These settings determine which items are part of the report to create either detailed or compact summary reports.

==== Testsuite ====
*'''Do not Print Testsuite Environment''' This option determines whether the testsuite environment, i.e. the variables defined in the current testsuite, are part of the test report. Please note that only variables which are defined as read-only will be shown in the report because the value of other variables can change during the test execution.

==== Testplan ====
*'''Do not Print Testplan Environment''' This option determines whether the environment of each executed testplan, i.e. the variables defined in the respective testplan, are included in the report. Please note that only variables which are defined as read-only will be shown in the report.

*'''Do not Print Successful Testcases''' This option removes all successful test cases from the report when checked, so that only failed tests are reported.

*'''Only Print Testplan Summary''' If checked, this option will reduce every testplan to a summary of the results of the different testplan items, i.e. it removes all further information such as sub-activities or logs.

*'''Print Unexecuted Test Cases''' This option also includes test cases in the report which have not been executed.

*'''Print Pre/Post Condition''' This option determines whether the pre- and post executions are presented in the report. There is also an option to include this information only for failed tests.

==== Activity ====
*'''Nesting Limit''' This option determines to which level nested sub-activities are reported. This affects the length and also the level of detail of the generated report.

*'''Activity Tags''' In order to include or exclude activities spawned by certain blocks from the report, you can add tags to each block. These tags can be set in the [[Documentation Editor|documentation tab]] of the block. Later you can filter the executed blocks by their tags. Please note that an inclusion to the report has priority over an exclusion.
**'''Include Tag(s)''' All blocks which have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Exclude Tag(s)''' All blocks which do not have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Sub-activities Include Tag(s)''' All sub activities which have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Sub-activities Exclude Tag(s)''' All sub activities which do not have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Search Tags in Children''' This option determines whether the sub-activities of an activity are searched for existing tags, when filtering.

*'''Print Input/Output Pins''' This option determines whether the data of input and output pins is present in the report. You can also add this information only in case the execution failed.

*'''Do not Print Output Pins''' This option removes the data of the output pins from the report, so that only input values are printed.

==== Logs ====
These settings are used to specify how logs are reported.

*'''Nesting Limit''' This option is used to determine down to which level logs of nested sub activities are reported.

*'''Log Tags''' In order to include or exclude logs of certain blocks from the report you can add tags to each block. Please note that an inclusion to the report has priority over an exclusion.
**'''Include Tag(s)''' All logs of blocks which have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Exclude Tag(s)''' All logs of blocks which do not have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Search Tags in Children''' This option determines whether the sub activities of an activity are searched for existing tags when filtering.

*'''Log Types''' These checkboxes are used to include or exclude different log message types from the report. Please note that there is a difference between logs that only change the state of an activity, e.g. "logFail", and real exceptions that stop the execution, e.g. "fail". The "All" button is used to toggle all types.

=== Modifications ===
==== Custom Test Cases ====
When reporting a test plan result, only the test cases of the top test plan are printed as test cases in the report by default. The report chart including count "passed", count "failed" etc. is based on those test cases. Also the flat overview list in the report is based on those test cases. In some cases, the test cases in the top test plan do not represent the actual test cases. The actual test cases can be nested deeper in the results tree, perhaps as test cases of a nested test plan, or perhaps as simple activities. Here you are able to define which activities have to be presented as test cases in the report (instead of the test cases of the top test plan).

*'''Include Nested Test Cases''' [[Bild:ReportNestedTestCasesOn.png|200px|thumb|right|Default vs. "Include Nested Test Cases"]]If checked all nested test cases (list items of nested test plans) will count as test cases (instead of just the list items of the root test plan).

*'''Include Activities''' [[Bild:ReportIncludeActivity.png|200px|thumb|right|Default vs. "Include Activity"]]If checked you can select activities (every result tree item, regardless if test case, test plan, compound, elementary etc.) which will be presented as test cases of one test plan.

*'''Activities with Tag''' Select activities which have at least one matching tag.

*'''Activities with Tag''' Select activities by their name.

*'''Completely Match''' The full name must match completely, if not a matching substring is sufficient.

*'''Use Match Pattern''' If checked, you are able to define a match pattern string for the activity name.

*'''Include Unexecuted Testcases''' [[Bild:ReportIncludeUnexecuted.png|200px|thumb|right|Default vs. "Include Unexecuted"]]If checked also unexecuted but as test case expected activities will count as test case.

=== Presentation Settings ===
[[Bild:Report Presentation Settings.png|thumb|200px|Presentation Settings]]
These settings are used to determine how the report is presented.

==== Common ====
*'''Print Full Activity Name''' This option determines whether the name of the corresponding block is printed when a step is reported. If the step-name is the same as the block name (which is the common case), then that option does not make a difference. But if a step has been renamed from the underlying block's name, then both names will be printed if they are different.

*'''Print Activity Name in Logs as Well''' This option determines whether the name of the activity which logged a message will be printed in front of the message.

*'''Indention Level Limit''' This option is used to determine to which nesting level reported sub activities are indented.

*'''Highlight Top State in Every Row''' This option adds a colored area with the top state color in every row. This helps to keep track of the overall test case result in case that many sub activities are reported.

*'''Page Break after Testplan Summary''' This option will add a page break after a testplan summary.

*'''Page Break after every Testcase''' This option will add a page break after every test case.

==== Fonts ====
These settings are used to change the fonts used for the document, the column headers and the activity reports.

==== Colors ====
These settings are used to change the color of different report items. Its possible to use the default color as defined in the [[Settings#State Colors|settings]] for error and failure logs. You can also print a "Only Black & White" report by toggling the corresponding check-box.

=== Test Overview Settings ===
[[Bild:Report Test Overview Settings.png|200px|thumb|Test Overview Settings]]
These settings can be used to customize the report summary.

*'''Testplan Summary''' Here you can specify how the summary of a testplan is presented. The editor panel is described here: [[Report Generation#Editor Panel|Editor Panel]]
*'''Activity Summary''' Here you can specify how the summary of an activity is presented. The editor panel is described here: [[Report Generation#Editor Panel|Editor Panel]]

=== Document Settings ===
[[Bild:Report Document Settings.png|thumb|200px|Document Settings]]
These settings apply on the general design of the report. Note that the header and footer line will only be present in a PDF report.

*'''Document Header''' Here you can create a header for the report. The editor panel is described here: [[Report Generation#Editor Panel|Editor Panel]]
*'''Columns Width''' Here you can resize the three columns of the report. Please note that each column has to fill at least 10 percent of the entire width.
*'''Header''' These text fields are used to edit the header line of the report. The left fields are used to enter left aligned text, the center ones for center aligned text and the right ones for right aligned text. You can also create links by typing a target into the "link" fields under the text fields.
*'''Footer''' These text fields are used to edit the footer line of the report. The usage is similar to the header line fields.

=== Logo Settings ===
These settings are used to specify images, e.g. company logos, which can be used in the report. By default the expecco logo is used. To replace the default images just click on the "replace" button behind the filenames and select the new image's file in the file dialog. Please note that the file type has to be ".jpg".

=== Description ===
Here you can add a description for the report template. This can be useful to inform other users for example when to use this template.

== Editor Panel ==

This editor panel is used to create style information for report summaries and the report header.

The workspace is made up of a number of rows which are separated columns (limited to a maximum of 6 columns). A single field is called cell. It can contain either text or graphics, such as a pie chart or a logo.

To enter text, double click on the cell causing a text editor to open.

To insert graphics, right click on a cell and select "''Insert Graphic''". Now you can select the type of the graphic. Please note that pie charts are only available for testplan reports and logos only for the document header.

Inside text, the content of a placeholder variable, such as the name of the testsuite or the current date can be inserted: double click on a cell to open the editor and right click to open the context menu. Now select "''Insert Variable''" and choose one of the variables from the list.
Currently, variables available in a testplan overview are:
* %testplan_name% - The name of the testplan
* %testcases_size% - The number of testcases in the testplan
* %testcases_executed% - The number of testcases in the report
* %hostname% - The hostname of the executing machine
* %username% - The username (login name)
* %start_date% - The date when the testplan was started
* %start_time% - The time when the testplan was started
* %run_time% - the overall execution time of the testplan (when finished)
* %elapsed_time% - the elapsed execution time of the testplan (only useful if a GenerateReport block is used from within an executing testplan. same as run_time when finished)

Variables available in an activity-overview are:
* %action_name% - The name of the activity
* %hostname% - The hostname of the executing machine
* %username% - The username (login name)
* %start_date% - The time when the activity was started
* %start_time% - The time when the activity was started
* %run_time% - the execution time of the activity

=== Buttons ===
*[[Bild:Icon Insert Row.png]] Inserts a new row after the selected one
*[[Bild:Icon Insert Column.png]] Inserts a new column right from the selected one. Please note that only the selected row is affected.
*[[Bild:Icon Remove Row.png]] Removes the selected row
*[[Bild:Icon Remove Column.png]] Removes the selected column
*[[Bild:Icon Report Move Up.png]] [[Bild:Icon Report Move Down.png]] Moves the selected row up/down
*[[Bild:Icon Report Move Left.png]] [[Bild:Icon Report Move Right.png]] Moves the selected column left/right
*[[Bild:Icon Open Editor.png]] Opens an editor to modify the content of the selected column
*[[Bild:Icon Save Close Editor.png]] Closes the editor with saving changes
*[[Bild:Icon NoSave Close Editor.png]] Closes the editor without saving changes
*[[Bild:Icon Left Alignment.png]] [[Bild:Icon Center Alignment.png]] [[Bild:Icon Right Alignment.png]] Aligns the content of the column left/center/right
*[[Bild:Icon Show Hide Grid.png]] Shows/Hides a grid to resize the columns

== Report vs. expecco Log-File ==


In contrast to the generated reports, which are meant to be either human readable archived documents (HTML, PDF, text) or machine readable, to be processed by other programs (CSV, XML),
there is another, expecco-internal storage format, the so called "expecco log files", with a ".elf" extension.
These files store all relevant tree elements, log data, in- and output in values which are required to reconstruct a full activity log/result tree.
This also means, that they include a copy of the executed blocks and their definitions, independent of any changes done to the test suite in the meantime. As such, they can be also archived to proof exactly which version of a suite was executed.

Just like regular reports, these log files can be generated after the execution of a test (both single block- and full testplan tests), and saved to a file:

[[Datei:Save_elf1.png‎]]

 

expecco ALM (formerly called "expeccoNET") also provides central storage of all log files and makes them available later to team members with appropriate access rights.


[[Datei:Save_elf2.png]]

As you can see, there is a menu item named "Load Test-Results (from expeccoNET)“ which loads those ".elf" files from this central database. If you do not have expecco ALM installed, you have to save/load those from a regular file.
After loading, the result tree is presented as it was right after the execution. You can also navigate through the tree, see pin values and other artefacts (however, of course, objects which where present on remote systems and only referred to via a bridge connection are no longer available. If required, these should be marshaled to XML or any other textual format, if that is required).



Another advantage of this format is that additional reports can be generated at any time later. For example, you can generate a new report with a different layout, look or detail. For example, if your company logo has changed in the meanwhile, or the product department needs another, less detailed report.



[[Datei:Print_elf.png]]

== Example: Executive Summary vs. Developer Report ==
[[Bild:Report Executive Summary.png|thumb|links|200px|Executive Summary]] [[Bild:Report Developer Report.png|thumb|200px|Developer Report.]]
The main advantage of report templates is the possibility to create standardized reports for different purposes. This way you can for example create a condensed report as a summary for an executive or a very detailed one for the development team to track down error causes or to document a test run.

In the shown example the executive summary solely shows the overall test results which are visualized by a pie chart. Other irrelevant information has been removed to keep the report clear and readable. A corresponding template can be found here: [[Datei:Executive Summary Template.ert]]

The shown developer report is more detailed and shows all relevant data to track down a possible error. In this case all irrelevant data from the developer's point of view is left out. For example the pie chart might not be useful in this case. A corresponding template can be found here: [[Datei:Developer Report Template.ert]]

= Programmatic Report Generation =

In rare situations, the automatic generated reports are not sufficient to fullfill your needs. It may be required to conform to a particular document format, or contain additional data, or it may need to be postprocessed (for example: cryptographically signed).

For this, you can either take the automatic report and post-process it with an expecco action (this would be the case when it has to be signed), or create your report completely driven by your own actions.
In the following, a few examples are provided to show possible solutions:

== Postprocessing Reports ==

You can define a post processing action to be executed after a test run (find the field in the lower area of the test plan editor). This action will get the generated activity log as argument at its input pin. Notice that this activity log contains all traced pin data, timestamps, notes and attachment information. The action can walk through this object and generate arbitrary output. An example for this is found in the deployed demo/example folder ("LOG-Processing example" in "<CODE>demos/d11_LOG_Processing_Example.ets</CODE>").

== Generating CSV Report Files ==
If the default CSV format is not appropriate for your QM system, you may generate a fully custom CSV with the following procedure.

Collect the CSV rows (i.e. the raw data to be put into the CSV columns) during the run, and write a CSV file at the end.

For this:
* define an action, which creates an empty (sequencable) collection (i.e. "New OrderedCollection" will do).
* inside the action, store this created collection in a test suite variable (let's say: "collectedData")

[[Datei:Pre-action_csv_report.png|500px]]

* make this action a "pre-action" of your test plan
* during the run, add rows as required to the "collectedData" collection (give the vector to an "Add Element" step)

[[Datei:Collect data csv report.png|650px]]

* define an action which saves the collectedData to a CSV file (use the "Write CSV" action)

[[Datei:Post-action csv report.png|500px]]

* make this write-action a "post-action" of your test plan

[[Datei:Testplan csv report.png|650px]]

All of the above actions are found in the standard library; there is no need to do any textual coding.
However, if you prefer scripts, you can of course do so as well.

== Generating a PDF Report ==

[[Datei:PDFGeneratorLibrary.png|mini]]
As part of the expecco installation, a PDF generator library is provided, which contains building blocks for PDF documents.
Similar to the above strategy, start PDF generation in a pre-action, collect data during the run and write the final PDF in a post-action at the end.

2021-12-07T10:46:04Z

Sr: /* Custom Test Cases */

= Automatic Report Generation =

Expecco can generate reports in a number of formats: as human readable PDF or HTML documents, or as machine readable XML-, CSV- or plain text containing all relevant information on the test execution. XML reports are further provided in 3 different formats: Junit compatible, Nunit compatible and the full detail XML.

The full detail XML contains all data as collected during the run, including timestamps and input-/output values of every logged activity. By using XML and a processor such as XSLT, any custom report can be generated from it, if the other reports are not sufficient.

In addition, you can also save an ".elf" file (which stands for "''expecco log file''").
This can later be reopened with expecco, to present the same view as after the run (i.e. the whole hierarchical execution trace is shown). Then, the test can be reexecuted or additional reports can be generated (possibly with different detail settings).

== Report Templates ==
Report templates are used to specify the content and layout of created human readable reports. By default the so called "''Default Report Template''" is used, which is remembered in your user settings.
Other report templates can be created as tree elements and stored in the testsuite. They will be saved together with the testsuite.

The "''Default Report Template''" is stored in your settings file and thus private, whereas attached report templates are contained in the saved test suite file, and thus automatically available to everyone who gets the testsuite.

== How to create a report ==
[[Bild:Report Settings.png|thumb|200px|Report Settings]]
To create a report, a test has to be executed first (or a ".elf" file be loaded from a previous run).
This can be either a single block test or a whole testplan. After the execution is finished, click on the "''Print report''" button ([[Bild:Icon Print Report.png|Report button]]) causing a dialog to open.

Select the output format (PDF, HTML, XML, CSV or TEXT), the report language, a paper format and a template for the report. This template can be the default report template, a template from the current testsuite or a template which is stored separately in a file. You can also make ad-hoc changes to the printed report right before it is generated, by clicking on "''Edit Default Report Template''" in the 'Generate Report' dialog. There, you can specify the detail and the look of the report (depth, detail, filter, company, logos, colours, fonts, etc.).

Choose the format of the file(s) to be generated; you may select multiple output formats here.

Human readable formats are:
* '''PDF''' - for printable document
* '''HTML''' - to publish as an intranet or public web page
Machine readable formats are:
* '''XML''' - contains full detail
* '''jUnit''' - jUnit compatible XML (1)
* '''nUnit''' - nUnit compatible XML (2)
* '''CSV''' - to be imported into excel or word
* '''Text''' - plain text (3)

If the "''Open Preview''" box is checked, the generated reports are shown in a preview application. Otherwise, they are silently generated in the folder as specified in your report settings.

Now click on "''Generate Report''" in the 'Generate Report' dialog,
(with the "''Open Preview''" checked, to see the output).

Notes: 
(1) the jUnit format is compatible to the output generated by corresponding Java unit testing frameworks. The jUnit format is documented in [https://github.com/windyroad/JUnit-Schema/blob/master/JUnit.xsd "https ://github.com/windyroad/JUnit-Schema/blob/master/JUnit.xsd"]. These files can be imported by eg. Jenkins to generate trend- and statistic reports. For how to integrate expecco into Jenkins, see [https://doc.expecco.de/wiki2.x/Starting_expecco_via_Command_Line/en#Integration_with_Jenkins "Integration with Jenkins"] in the doc-Wiki.

(2) the nUnit format is compatible to the output generated by corresponding .NET unit testing frameworks.

(3) this simple format may be useful if the test result is to be sent as email or as an instant message (eg. Jabber)

== How to Add a Report Template to the Tree ==
It is a good idea to add templates to the project's tree. Often users wish to generate both a full-detail report for developers and a summary report for the management. Also, quality reports for final test before delivery usually provide less detail and may be signed with a barcode or QR tag (which can be generated by expecco and placed into a PDF, for example).

In the tree, select "''New Report Template''", give it a reasonable name, and modify its settings.
For a summary report, you will usually set a limit on the depth (i.e. not showing sub activities) and not showing pin values. You may also set a filter, to only present values or actions with a particular tag.

== Importing Report Templates ==
You can also put a number of report templates into a separate import library, to ensure that all test suites use a common (corporate identity conform) layout and detail.

== How to Customize a Report Template ==
To customize a report template, select it in the navigation tree. The same editor is used as when modifying the default report template.

=== Filter Settings ===
[[Bild:Report Filter Settings.png|thumb|200px|Filter Settings]]
These settings determine which items are part of the report to create either detailed or compact summary reports.

==== Testsuite ====
*'''Do not Print Testsuite Environment''' This option determines whether the testsuite environment, i.e. the variables defined in the current testsuite, are part of the test report. Please note that only variables which are defined as read-only will be shown in the report because the value of other variables can change during the test execution.

==== Testplan ====
*'''Do not Print Testplan Environment''' This option determines whether the environment of each executed testplan, i.e. the variables defined in the respective testplan, are included in the report. Please note that only variables which are defined as read-only will be shown in the report.

*'''Do not Print Successful Testcases''' This option removes all successful test cases from the report when checked, so that only failed tests are reported.

*'''Only Print Testplan Summary''' If checked, this option will reduce every testplan to a summary of the results of the different testplan items, i.e. it removes all further information such as sub-activities or logs.

*'''Print Unexecuted Test Cases''' This option also includes test cases in the report which have not been executed.

*'''Print Pre/Post Condition''' This option determines whether the pre- and post executions are presented in the report. There is also an option to include this information only for failed tests.

==== Activity ====
*'''Nesting Limit''' This option determines to which level nested sub-activities are reported. This affects the length and also the level of detail of the generated report.

*'''Activity Tags''' In order to include or exclude activities spawned by certain blocks from the report, you can add tags to each block. These tags can be set in the [[Documentation Editor|documentation tab]] of the block. Later you can filter the executed blocks by their tags. Please note that an inclusion to the report has priority over an exclusion.
**'''Include Tag(s)''' All blocks which have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Exclude Tag(s)''' All blocks which do not have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Sub-activities Include Tag(s)''' All sub activities which have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Sub-activities Exclude Tag(s)''' All sub activities which do not have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Search Tags in Children''' This option determines whether the sub-activities of an activity are searched for existing tags, when filtering.

*'''Print Input/Output Pins''' This option determines whether the data of input and output pins is present in the report. You can also add this information only in case the execution failed.

*'''Do not Print Output Pins''' This option removes the data of the output pins from the report, so that only input values are printed.

==== Logs ====
These settings are used to specify how logs are reported.

*'''Nesting Limit''' This option is used to determine down to which level logs of nested sub activities are reported.

*'''Log Tags''' In order to include or exclude logs of certain blocks from the report you can add tags to each block. Please note that an inclusion to the report has priority over an exclusion.
**'''Include Tag(s)''' All logs of blocks which have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Exclude Tag(s)''' All logs of blocks which do not have one or more of those tags will be present in the report. Multiple tags must be separated by ";".
**'''Search Tags in Children''' This option determines whether the sub activities of an activity are searched for existing tags when filtering.

*'''Log Types''' These checkboxes are used to include or exclude different log message types from the report. Please note that there is a difference between logs that only change the state of an activity, e.g. "logFail", and real exceptions that stop the execution, e.g. "fail". The "All" button is used to toggle all types.

=== Modifications ===
==== Custom Test Cases ====
When reporting a test plan result, only the test cases of the top test plan are printed as test cases in the report by default. The report chart including count "passed", count "failed" etc. is based on those test cases. Also the flat overview list in the report is based on those test cases. In some cases, the test cases in the top test plan do not represent the actual test cases. The actual test cases can be nested deeper in the results tree, perhaps as test cases of a nested test plan, or perhaps as simple activities. Here you are able to define which activities have to be presented as test cases in the report (instead of the test cases of the top test plan).

*'''Include Nested Test Cases''' 
If checked all nested test cases (list items of nested test plans) will count as test cases (instead of just the list items of the root test plan).
[[Bild:ReportNestedTestCasesOn.png]]

=== Presentation Settings ===
[[Bild:Report Presentation Settings.png|thumb|200px|Presentation Settings]]
These settings are used to determine how the report is presented.

==== Common ====
*'''Print Full Activity Name''' This option determines whether the name of the corresponding block is printed when a step is reported. If the step-name is the same as the block name (which is the common case), then that option does not make a difference. But if a step has been renamed from the underlying block's name, then both names will be printed if they are different.

*'''Print Activity Name in Logs as Well''' This option determines whether the name of the activity which logged a message will be printed in front of the message.

*'''Indention Level Limit''' This option is used to determine to which nesting level reported sub activities are indented.

*'''Highlight Top State in Every Row''' This option adds a colored area with the top state color in every row. This helps to keep track of the overall test case result in case that many sub activities are reported.

*'''Page Break after Testplan Summary''' This option will add a page break after a testplan summary.

*'''Page Break after every Testcase''' This option will add a page break after every test case.

==== Fonts ====
These settings are used to change the fonts used for the document, the column headers and the activity reports.

==== Colors ====
These settings are used to change the color of different report items. Its possible to use the default color as defined in the [[Settings#State Colors|settings]] for error and failure logs. You can also print a "Only Black & White" report by toggling the corresponding check-box.

=== Test Overview Settings ===
[[Bild:Report Test Overview Settings.png|200px|thumb|Test Overview Settings]]
These settings can be used to customize the report summary.

*'''Testplan Summary''' Here you can specify how the summary of a testplan is presented. The editor panel is described here: [[Report Generation#Editor Panel|Editor Panel]]
*'''Activity Summary''' Here you can specify how the summary of an activity is presented. The editor panel is described here: [[Report Generation#Editor Panel|Editor Panel]]

=== Document Settings ===
[[Bild:Report Document Settings.png|thumb|200px|Document Settings]]
These settings apply on the general design of the report. Note that the header and footer line will only be present in a PDF report.

*'''Document Header''' Here you can create a header for the report. The editor panel is described here: [[Report Generation#Editor Panel|Editor Panel]]
*'''Columns Width''' Here you can resize the three columns of the report. Please note that each column has to fill at least 10 percent of the entire width.
*'''Header''' These text fields are used to edit the header line of the report. The left fields are used to enter left aligned text, the center ones for center aligned text and the right ones for right aligned text. You can also create links by typing a target into the "link" fields under the text fields.
*'''Footer''' These text fields are used to edit the footer line of the report. The usage is similar to the header line fields.

=== Logo Settings ===
These settings are used to specify images, e.g. company logos, which can be used in the report. By default the expecco logo is used. To replace the default images just click on the "replace" button behind the filenames and select the new image's file in the file dialog. Please note that the file type has to be ".jpg".

=== Description ===
Here you can add a description for the report template. This can be useful to inform other users for example when to use this template.

== Editor Panel ==

This editor panel is used to create style information for report summaries and the report header.

The workspace is made up of a number of rows which are separated columns (limited to a maximum of 6 columns). A single field is called cell. It can contain either text or graphics, such as a pie chart or a logo.

To enter text, double click on the cell causing a text editor to open.

To insert graphics, right click on a cell and select "''Insert Graphic''". Now you can select the type of the graphic. Please note that pie charts are only available for testplan reports and logos only for the document header.

Inside text, the content of a placeholder variable, such as the name of the testsuite or the current date can be inserted: double click on a cell to open the editor and right click to open the context menu. Now select "''Insert Variable''" and choose one of the variables from the list.
Currently, variables available in a testplan overview are:
* %testplan_name% - The name of the testplan
* %testcases_size% - The number of testcases in the testplan
* %testcases_executed% - The number of testcases in the report
* %hostname% - The hostname of the executing machine
* %username% - The username (login name)
* %start_date% - The date when the testplan was started
* %start_time% - The time when the testplan was started
* %run_time% - the overall execution time of the testplan (when finished)
* %elapsed_time% - the elapsed execution time of the testplan (only useful if a GenerateReport block is used from within an executing testplan. same as run_time when finished)

Variables available in an activity-overview are:
* %action_name% - The name of the activity
* %hostname% - The hostname of the executing machine
* %username% - The username (login name)
* %start_date% - The time when the activity was started
* %start_time% - The time when the activity was started
* %run_time% - the execution time of the activity

=== Buttons ===
*[[Bild:Icon Insert Row.png]] Inserts a new row after the selected one
*[[Bild:Icon Insert Column.png]] Inserts a new column right from the selected one. Please note that only the selected row is affected.
*[[Bild:Icon Remove Row.png]] Removes the selected row
*[[Bild:Icon Remove Column.png]] Removes the selected column
*[[Bild:Icon Report Move Up.png]] [[Bild:Icon Report Move Down.png]] Moves the selected row up/down
*[[Bild:Icon Report Move Left.png]] [[Bild:Icon Report Move Right.png]] Moves the selected column left/right
*[[Bild:Icon Open Editor.png]] Opens an editor to modify the content of the selected column
*[[Bild:Icon Save Close Editor.png]] Closes the editor with saving changes
*[[Bild:Icon NoSave Close Editor.png]] Closes the editor without saving changes
*[[Bild:Icon Left Alignment.png]] [[Bild:Icon Center Alignment.png]] [[Bild:Icon Right Alignment.png]] Aligns the content of the column left/center/right
*[[Bild:Icon Show Hide Grid.png]] Shows/Hides a grid to resize the columns

== Report vs. expecco Log-File ==


In contrast to the generated reports, which are meant to be either human readable archived documents (HTML, PDF, text) or machine readable, to be processed by other programs (CSV, XML),
there is another, expecco-internal storage format, the so called "expecco log files", with a ".elf" extension.
These files store all relevant tree elements, log data, in- and output in values which are required to reconstruct a full activity log/result tree.
This also means, that they include a copy of the executed blocks and their definitions, independent of any changes done to the test suite in the meantime. As such, they can be also archived to proof exactly which version of a suite was executed.

Just like regular reports, these log files can be generated after the execution of a test (both single block- and full testplan tests), and saved to a file:

[[Datei:Save_elf1.png‎]]

 

expecco ALM (formerly called "expeccoNET") also provides central storage of all log files and makes them available later to team members with appropriate access rights.


[[Datei:Save_elf2.png]]

As you can see, there is a menu item named "Load Test-Results (from expeccoNET)“ which loads those ".elf" files from this central database. If you do not have expecco ALM installed, you have to save/load those from a regular file.
After loading, the result tree is presented as it was right after the execution. You can also navigate through the tree, see pin values and other artefacts (however, of course, objects which where present on remote systems and only referred to via a bridge connection are no longer available. If required, these should be marshaled to XML or any other textual format, if that is required).



Another advantage of this format is that additional reports can be generated at any time later. For example, you can generate a new report with a different layout, look or detail. For example, if your company logo has changed in the meanwhile, or the product department needs another, less detailed report.



[[Datei:Print_elf.png]]

== Example: Executive Summary vs. Developer Report ==
[[Bild:Report Executive Summary.png|thumb|links|200px|Executive Summary]] [[Bild:Report Developer Report.png|thumb|200px|Developer Report.]]
The main advantage of report templates is the possibility to create standardized reports for different purposes. This way you can for example create a condensed report as a summary for an executive or a very detailed one for the development team to track down error causes or to document a test run.

In the shown example the executive summary solely shows the overall test results which are visualized by a pie chart. Other irrelevant information has been removed to keep the report clear and readable. A corresponding template can be found here: [[Datei:Executive Summary Template.ert]]

The shown developer report is more detailed and shows all relevant data to track down a possible error. In this case all irrelevant data from the developer's point of view is left out. For example the pie chart might not be useful in this case. A corresponding template can be found here: [[Datei:Developer Report Template.ert]]

= Programmatic Report Generation =

In rare situations, the automatic generated reports are not sufficient to fullfill your needs. It may be required to conform to a particular document format, or contain additional data, or it may need to be postprocessed (for example: cryptographically signed).

For this, you can either take the automatic report and post-process it with an expecco action (this would be the case when it has to be signed), or create your report completely driven by your own actions.
In the following, a few examples are provided to show possible solutions:

== Postprocessing Reports ==

You can define a post processing action to be executed after a test run (find the field in the lower area of the test plan editor). This action will get the generated activity log as argument at its input pin. Notice that this activity log contains all traced pin data, timestamps, notes and attachment information. The action can walk through this object and generate arbitrary output. An example for this is found in the deployed demo/example folder ("LOG-Processing example" in "<CODE>demos/d11_LOG_Processing_Example.ets</CODE>").

== Generating CSV Report Files ==
If the default CSV format is not appropriate for your QM system, you may generate a fully custom CSV with the following procedure.

Collect the CSV rows (i.e. the raw data to be put into the CSV columns) during the run, and write a CSV file at the end.

For this:
* define an action, which creates an empty (sequencable) collection (i.e. "New OrderedCollection" will do).
* inside the action, store this created collection in a test suite variable (let's say: "collectedData")

[[Datei:Pre-action_csv_report.png|500px]]

* make this action a "pre-action" of your test plan
* during the run, add rows as required to the "collectedData" collection (give the vector to an "Add Element" step)

[[Datei:Collect data csv report.png|650px]]

* define an action which saves the collectedData to a CSV file (use the "Write CSV" action)

[[Datei:Post-action csv report.png|500px]]

* make this write-action a "post-action" of your test plan

[[Datei:Testplan csv report.png|650px]]

All of the above actions are found in the standard library; there is no need to do any textual coding.
However, if you prefer scripts, you can of course do so as well.

== Generating a PDF Report ==

[[Datei:PDFGeneratorLibrary.png|mini]]
As part of the expecco installation, a PDF generator library is provided, which contains building blocks for PDF documents.
Similar to the above strategy, start PDF generation in a pre-action, collect data during the run and write the final PDF in a post-action at the end.

2021-03-04T10:55:01Z

Sr: /* Installation */

==Übersicht==

Der expecco Lizenzserver dient der zentralen Verwaltung von expecco Lizenzen. Durch den Lizenzserver kann expecco auf verschiedenen Rechnern (sowohl Entwicklungs- als auch reine Testausführungsrechner) ohne Dongle und lokale Lizenzdatei auf allen erreichbaren Rechnern im Netz installiert und ausgeführt werden.

Lizenzen werden dabei von den expecco-Rechnern vom Lizenzserver angefordert, im Lizenzserver reserviert,
und nach der Sitzung bzw. Testlauf wieder zurückgegeben. Damit können mehr Nutzer (allerdings nicht gleichzeitig) mit expecco arbeiten als Lizenzen erworben wurden.

Lizenzen sind kryptographisch gesicherte Dateien, welche nur in Verbindung mit einem von eXept gelieferten Lizenzserver-Dongle gelesen bzw. genutzt werden können. Lizenzen sind Dongle-spezifisch. Es ist also nicht notwendig, Maßnahmen zum Schutz vor Diebstahl oder Kopieren von Lizenzdateien zu ergreifen. Allerdings ist ein Verlust des Dongles aus nahe liegenden Gründen zu vermeiden.

{{SEITENTITEL:Lizenzservice Installation}}

== Voraussetzungen ==
Wir empfehlen expecco ALM auf einem durchgehend verfügbaren Server mit Windows Server 2008 / Windows 7 oder höher zu installieren. Die Installation auf anderen Betriebssystemen wäre bei Bedarf auch möglich. Ebenso ist die Installation in einer Cloud möglich, dort ist der Betrieb ohne Dongle möglich.

Damit expecco ALM flüssig arbeiten kann, werden folgende Hardware-Anforderungen an den Server gestellt:
 - ein "dezidierter" Prozessor mit mindestens 2 GHz
 - mindestens 1 GB Arbeitsspeicher (ausschließlich für expecco ALM)
 - mindestens 10 GB Festplattenspeicher (je nach Größe der Daten die expecco ALM verwalten soll)

Stellen Sie sicher, dass dieser Server für alle Clients erreichbar ist. Clients sind alle Rechner der expecco ALM Benutzer, Rechner die expecco ALM zur Testausführung dienen und Rechner mit "Floating" lizenziertem expecco. Bei Problemen bezüglich der Erreichbarkeit wenden Sie sich bitte an Ihren Netzwerkadministrator.

== Installation ==

Bitte halten Sie Ihre Lizenzdatei und Ihren Dongle für die Installation von expecco ALM bereit. 
Für die Installation in der Cloud liefern wir eine Lizenzdatei mit entsprechender Mac-Adresse.

Ihre Lizenzdatei und eine Verknüpfung zum aktuellen expecco ALM Setup haben wir Ihnen per E-Mail zu kommen lassen. Der Installer hat folgenden Namen "expecco ALM 1.9.0.1 Setup.exe", wobei die Versionsnummer abweichen kann. Ihren Dongle haben wir per Post an Sie versendet (es sei denn Sie evaluieren expecco ALM oder nutzen die Cloud Variante mit der Mac-Adressen-Bindung).

Gehen Sie bitte wie folgt vor:
 - Laden Sie den expecco ALM Installer auf dem Server, auf dem expecco ALM künftig laufen soll, herunter
 - Legen Sie Ihre Lizenzdatei ebenfalls auf dem Server ab
 - Verbinden Sie Ihren Dongle mit dem Server (Wenn Sie expecco ALM evaluieren oder die Cloud Variante mit der Mac-Adressen-Bindung nutzen, überspringen Sie diesen Schritt)
 - Führen Sie den expecco ALM Installer ("expecco ALM ?.?.?.? Setup.exe") aus

Nachdem der Installer erfolgreich ausgeführt wurde, läuft expecco ALM bereits als Service. Auf Ihrem Desktop wurde eine Verknüpfung zu expecco ALM angelegt. Es wurde auch ein Ordner für expecco ALM in Ihrem Startmenü erstellt. Dort können Sie unter "Konfiguration" den Port ändern (Standard ist Port 8081) oder über die "Logdatei" eventuelle Probleme feststellen.

[[Datei:InstallAlmLicense.png|mini|Anhang 1]]
Über die Verknüpfung auf Ihrem Desktop lässt sich expecco ALM mit Ihrem Standardbrowser öffnen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei (die Sie bereits auf dem Server abgelegt haben) auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen. Wenn bereits eine gültige Lizenz installiert ist, wird stattdessen die Anmeldeseite angezeigt. Falls es sich bei Ihnen um eine Erstinstallation handelt, können Sie sich mit Anmeldenamen "admin" und Kennwort "admin" anmelden.

Falls eine leere Seite oder eine Fehlerseite angezeigt wird, probieren Sie einen anderen Port aus und/oder schauen Sie in der Logdatei nach Fehlermeldungen.

== SSL-Verschlüsselung / Proxy-Server ==
expecco ALM unterstützt aktuell noch nicht direkt SSL-Verschlüsselung. Über einen Proxy-Server ist diese aber problemlos einzurichten, z.B. über einen Apache-Server. Falls auf ihrem Server weitere Webseiten gehostet werden, ist dies ja ohnehin erforderlich, da sich nicht mehrere Prozesse gleichzeitig an den Port 443 binden können.

Eine Apache2 VirtualHost-Konfiguration würde entsprechend so aussehen (angenommen expecco ALM läuft mit Port 8466 - erforderliche Anpassung für ihre Konfiguration fett):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

Die SSL-Parameter mit dem Pfaden zu Ihren Zertifkaten uns Schlüsseln würden in diesem Konfigurations-Beispiel in der Apache-globalen Datei /etc/letsencrypt/ssl-xyz.de.conf liegen.

== Hinweise zur Lizenzierung ==
Wenn Sie expecco ALM erworben haben, erhalten Sie einen Dongle und eine Lizenzdatei. Falls Sie expecco ALM evaluieren, erhalten Sie ausschließlich die Lizenzdatei. Die Lizenzdatei beinhaltet eine für Sie individuelle expecco ALM Lizenz. So sind zum Beispiel: Der Name Ihrer Firma, für Sie freigeschaltete Module oder die Gültigkeitsdauer in der Lizenz hinterlegt. Der Dongle muss (insofern Sie expecco ALM erworben haben) ständig mit dem Server, auf dem expecco ALM ausgeführt wird, verbunden sein. Falls Sie den Dongle während des Betriebs abziehen, wird expecco ALM seinen Dienst einstellen.

== Lizenz wechseln ==
[[Datei:ChangeAlmLicense.png|mini|Anhang 2]]
Falls Sie eine aktuelle expecco ALM Version haben, können Sie eine neue Lizenzdatei "expecco ALM Lizenz *.lic" über das Webinterface von expecco ALM einspielen. Betrachten Sie dazu den angehängten Screenshot (Anhang 2).

Fall Sie eine ältere expecco ALM Version haben, müssen Sie folgendermaßen vorgehen:
 - Da Sie expecco ALM später neustarten müssen, tätigen Sie entsprechende Vorsorgemaßnahmen (Bspw. Benutzer abmelden, Datenbank sichern usw.)
 - Melden Sie sich auf dem Computer, der expecco ALM betreibt an
 - Begeben Sie sich in folgendes Verzeichnis "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM" oder falls es sich um ein 32Bit Betriebssystem handelt "C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM" und löschen Sie die Datei "expecco_ALM.lic"
 - Starten Sie den expecco ALM Service über den Windows-Service-Manager neu oder beenden Sie über den Windows-Task-Manager den Prozess "expecco_ALM.exe", in letzterem Fall wird der Windows-Service-Manager expecco ALM automatisch neustarten.
 - Nun können Sie das expecco ALM Webinterface aufrufen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei. auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen.

== Einbringen von expecco Floating-Lizenzen ==
Der Lizenzservice von expecco ALM vergibt verfügbare expecco Floating-Lizenzen aus einem bestimmten Pool. 
In diesen zunächst leeren Pool können von eXept erworbene expecco Floating-Lizenzen eingebracht werden.
 
Diese expecco Floating-Lizenzen erhalten Sie als Lizenzdatei(en) üblicherweise per E-Mail. 
Eine Lizenzdatei kann eine oder mehrere expecco Floating-Lizenzen auch für verschiedene Komponenten (Basissystem, Plugins und Erweiterungen) enthalten. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.
 
expecco Floating-Lizenzen werden immer spezifisch für eine expecco ALM Lizenz erstellt und sind nur mit dieser und deren Dongle nutzbar. 
Es ist also nicht notwendig solche Lizenzdateien unter Verschluss zu halten oder über eine sichere Verbindung auszutauschen. 
Allerdings sollten Sie den Dongle sicher aufbewahren bzw. Diebstahl vorbeugen.
 
Zur Einbringen einer expecco Floating-Lizenz öffnen Sie expecco ALM und melden Sie sich an. 
Jetzt navigieren Sie über die obere Hauptnavigationsleiste zum "Lizenzservice" Modul.
 
Sie befinden sich nun im Lizenzservice und Ihnen wird die Liste der installierten expecco Floating-Lizenzen angezeigt. 
Wechseln Sie zur Registerkarte "expecco Lizenzdateien". 
Navigieren Sie mithilfe des Navigationsmenüs auf der linken Seite zu "Hochladen/Upload". 
Hier können Sie nun durch ein einfaches Hochladen Ihrer expecco Floating-Lizenzen selbige in den Pool einbringen. 
In der zuvor genannte Liste werden nun die eben hochgeladenen expecco Floating-Lizenzen anzeigt. 
Diese sind von nun an auch von entfernten expecco Clients abrufbar. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.

== Lizenz Übersicht ==
Welche einzelnen expecco Floating-Lizenzen verfügbar oder vergeben sind, 
erfahren Sie indem Sie zur Registerkarte "expecco Lizenzen" wechseln. 
Insbesondere ist hieraus ersichtlich, welcher Rechner/Benutzer welche expecco Floating-Lizenz aktuell nutzt. 
Dies ist beispielsweise sinnvoll, wenn ein expecco Client seine Sitzung versehentlich nicht beendet hat, 
und andere Nutzer eine entsprechende Lizenz benötigen.

Lizenzserver expecco ALM

2021-03-04T10:54:01Z

Sr: /* Installation */

==Übersicht==

Der expecco Lizenzserver dient der zentralen Verwaltung von expecco Lizenzen. Durch den Lizenzserver kann expecco auf verschiedenen Rechnern (sowohl Entwicklungs- als auch reine Testausführungsrechner) ohne Dongle und lokale Lizenzdatei auf allen erreichbaren Rechnern im Netz installiert und ausgeführt werden.

Lizenzen werden dabei von den expecco-Rechnern vom Lizenzserver angefordert, im Lizenzserver reserviert,
und nach der Sitzung bzw. Testlauf wieder zurückgegeben. Damit können mehr Nutzer (allerdings nicht gleichzeitig) mit expecco arbeiten als Lizenzen erworben wurden.

Lizenzen sind kryptographisch gesicherte Dateien, welche nur in Verbindung mit einem von eXept gelieferten Lizenzserver-Dongle gelesen bzw. genutzt werden können. Lizenzen sind Dongle-spezifisch. Es ist also nicht notwendig, Maßnahmen zum Schutz vor Diebstahl oder Kopieren von Lizenzdateien zu ergreifen. Allerdings ist ein Verlust des Dongles aus nahe liegenden Gründen zu vermeiden.

{{SEITENTITEL:Lizenzservice Installation}}

== Voraussetzungen ==
Wir empfehlen expecco ALM auf einem durchgehend verfügbaren Server mit Windows Server 2008 / Windows 7 oder höher zu installieren. Die Installation auf anderen Betriebssystemen wäre bei Bedarf auch möglich. Ebenso ist die Installation in einer Cloud möglich, dort ist der Betrieb ohne Dongle möglich.

Damit expecco ALM flüssig arbeiten kann, werden folgende Hardware-Anforderungen an den Server gestellt:
 - ein "dezidierter" Prozessor mit mindestens 2 GHz
 - mindestens 1 GB Arbeitsspeicher (ausschließlich für expecco ALM)
 - mindestens 10 GB Festplattenspeicher (je nach Größe der Daten die expecco ALM verwalten soll)

Stellen Sie sicher, dass dieser Server für alle Clients erreichbar ist. Clients sind alle Rechner der expecco ALM Benutzer, Rechner die expecco ALM zur Testausführung dienen und Rechner mit "Floating" lizenziertem expecco. Bei Problemen bezüglich der Erreichbarkeit wenden Sie sich bitte an Ihren Netzwerkadministrator.

== Installation ==

Bitte halten Sie Ihre Lizenzdatei und Ihren Dongle für die Installation von expecco ALM bereit. 
Für die Installation in der Cloud liefern wir eine Lizenzdatei mit entsprechender Mac-Adresse.

Ihre Lizenzdatei und eine Verknüpfung zum aktuellen expecco ALM Setup haben wir Ihnen per E-Mail zu kommen lassen. Der Installer hat folgenden Namen "expecco ALM 1.9.0.1 Setup.exe", wobei die Versionsnummer abweichen kann. Ihren Dongle haben wir per Post an Sie versendet (es sei denn Sie evaluieren expecco ALM oder nutzen die Cloud Variante mit der Mac-Adressen-Bindung).

Gehen Sie bitte wie folgt vor:
 - Laden Sie den expecco ALM Installer auf dem Server, auf dem expecco ALM künftig laufen soll, herunter
 - Legen Sie Ihre Lizenzdatei ebenfalls auf dem Server ab
 - Verbinden Sie Ihren Dongle mit dem Server (Wenn Sie expecco ALM evaluieren, überspringen Sie diesen Schritt)
 - Führen Sie den expecco ALM Installer ("expecco ALM ?.?.?.? Setup.exe") aus

Nachdem der Installer erfolgreich ausgeführt wurde, läuft expecco ALM bereits als Service. Auf Ihrem Desktop wurde eine Verknüpfung zu expecco ALM angelegt. Es wurde auch ein Ordner für expecco ALM in Ihrem Startmenü erstellt. Dort können Sie unter "Konfiguration" den Port ändern (Standard ist Port 8081) oder über die "Logdatei" eventuelle Probleme feststellen.

[[Datei:InstallAlmLicense.png|mini|Anhang 1]]
Über die Verknüpfung auf Ihrem Desktop lässt sich expecco ALM mit Ihrem Standardbrowser öffnen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei (die Sie bereits auf dem Server abgelegt haben) auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen. Wenn bereits eine gültige Lizenz installiert ist, wird stattdessen die Anmeldeseite angezeigt. Falls es sich bei Ihnen um eine Erstinstallation handelt, können Sie sich mit Anmeldenamen "admin" und Kennwort "admin" anmelden.

Falls eine leere Seite oder eine Fehlerseite angezeigt wird, probieren Sie einen anderen Port aus und/oder schauen Sie in der Logdatei nach Fehlermeldungen.

== SSL-Verschlüsselung / Proxy-Server ==
expecco ALM unterstützt aktuell noch nicht direkt SSL-Verschlüsselung. Über einen Proxy-Server ist diese aber problemlos einzurichten, z.B. über einen Apache-Server. Falls auf ihrem Server weitere Webseiten gehostet werden, ist dies ja ohnehin erforderlich, da sich nicht mehrere Prozesse gleichzeitig an den Port 443 binden können.

Eine Apache2 VirtualHost-Konfiguration würde entsprechend so aussehen (angenommen expecco ALM läuft mit Port 8466 - erforderliche Anpassung für ihre Konfiguration fett):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

Die SSL-Parameter mit dem Pfaden zu Ihren Zertifkaten uns Schlüsseln würden in diesem Konfigurations-Beispiel in der Apache-globalen Datei /etc/letsencrypt/ssl-xyz.de.conf liegen.

== Hinweise zur Lizenzierung ==
Wenn Sie expecco ALM erworben haben, erhalten Sie einen Dongle und eine Lizenzdatei. Falls Sie expecco ALM evaluieren, erhalten Sie ausschließlich die Lizenzdatei. Die Lizenzdatei beinhaltet eine für Sie individuelle expecco ALM Lizenz. So sind zum Beispiel: Der Name Ihrer Firma, für Sie freigeschaltete Module oder die Gültigkeitsdauer in der Lizenz hinterlegt. Der Dongle muss (insofern Sie expecco ALM erworben haben) ständig mit dem Server, auf dem expecco ALM ausgeführt wird, verbunden sein. Falls Sie den Dongle während des Betriebs abziehen, wird expecco ALM seinen Dienst einstellen.

== Lizenz wechseln ==
[[Datei:ChangeAlmLicense.png|mini|Anhang 2]]
Falls Sie eine aktuelle expecco ALM Version haben, können Sie eine neue Lizenzdatei "expecco ALM Lizenz *.lic" über das Webinterface von expecco ALM einspielen. Betrachten Sie dazu den angehängten Screenshot (Anhang 2).

Fall Sie eine ältere expecco ALM Version haben, müssen Sie folgendermaßen vorgehen:
 - Da Sie expecco ALM später neustarten müssen, tätigen Sie entsprechende Vorsorgemaßnahmen (Bspw. Benutzer abmelden, Datenbank sichern usw.)
 - Melden Sie sich auf dem Computer, der expecco ALM betreibt an
 - Begeben Sie sich in folgendes Verzeichnis "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM" oder falls es sich um ein 32Bit Betriebssystem handelt "C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM" und löschen Sie die Datei "expecco_ALM.lic"
 - Starten Sie den expecco ALM Service über den Windows-Service-Manager neu oder beenden Sie über den Windows-Task-Manager den Prozess "expecco_ALM.exe", in letzterem Fall wird der Windows-Service-Manager expecco ALM automatisch neustarten.
 - Nun können Sie das expecco ALM Webinterface aufrufen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei. auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen.

== Einbringen von expecco Floating-Lizenzen ==
Der Lizenzservice von expecco ALM vergibt verfügbare expecco Floating-Lizenzen aus einem bestimmten Pool. 
In diesen zunächst leeren Pool können von eXept erworbene expecco Floating-Lizenzen eingebracht werden.
 
Diese expecco Floating-Lizenzen erhalten Sie als Lizenzdatei(en) üblicherweise per E-Mail. 
Eine Lizenzdatei kann eine oder mehrere expecco Floating-Lizenzen auch für verschiedene Komponenten (Basissystem, Plugins und Erweiterungen) enthalten. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.
 
expecco Floating-Lizenzen werden immer spezifisch für eine expecco ALM Lizenz erstellt und sind nur mit dieser und deren Dongle nutzbar. 
Es ist also nicht notwendig solche Lizenzdateien unter Verschluss zu halten oder über eine sichere Verbindung auszutauschen. 
Allerdings sollten Sie den Dongle sicher aufbewahren bzw. Diebstahl vorbeugen.
 
Zur Einbringen einer expecco Floating-Lizenz öffnen Sie expecco ALM und melden Sie sich an. 
Jetzt navigieren Sie über die obere Hauptnavigationsleiste zum "Lizenzservice" Modul.
 
Sie befinden sich nun im Lizenzservice und Ihnen wird die Liste der installierten expecco Floating-Lizenzen angezeigt. 
Wechseln Sie zur Registerkarte "expecco Lizenzdateien". 
Navigieren Sie mithilfe des Navigationsmenüs auf der linken Seite zu "Hochladen/Upload". 
Hier können Sie nun durch ein einfaches Hochladen Ihrer expecco Floating-Lizenzen selbige in den Pool einbringen. 
In der zuvor genannte Liste werden nun die eben hochgeladenen expecco Floating-Lizenzen anzeigt. 
Diese sind von nun an auch von entfernten expecco Clients abrufbar. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.

== Lizenz Übersicht ==
Welche einzelnen expecco Floating-Lizenzen verfügbar oder vergeben sind, 
erfahren Sie indem Sie zur Registerkarte "expecco Lizenzen" wechseln. 
Insbesondere ist hieraus ersichtlich, welcher Rechner/Benutzer welche expecco Floating-Lizenz aktuell nutzt. 
Dies ist beispielsweise sinnvoll, wenn ein expecco Client seine Sitzung versehentlich nicht beendet hat, 
und andere Nutzer eine entsprechende Lizenz benötigen.

Java GUI Plugins

2021-03-03T09:24:47Z

Sr: /* Verbindung zu Entfernten Systemen */

== Unterstützte Java-Technologien ==
expecco unterstützt die Automatisierung von Java-Anwendungen, die mit Java Swing, Java SWT oder JavaFX implementiert sind. Ebenso werden Anwendungen unterstützt, die mehrere dieser Technologien vereinen, z.B. eine Swing-Anwendung mit eingebettetem JavaFX-Inhalt.

=== Java Swing ===

Diese Erweiterung für expecco ermöglicht die Testautomatisierung von Java-Anwendungen, deren Benutzeroberflächen mit Swing erstellt wurden. Die Baustein-Bibliothek beinhaltet Blöcke zur Steuerung und Überprüfung von Swing-Benutzeroberflächen. Zudem integriert sich diese Erweiterung in die [[Expecco GUI Tests_Extension Reference|expecco GUI Test Extension]]. Diese dient der Unterstützung bei der Entwicklung von Testsequenzen.

==== Hauptmerkmale ====

* Automatisierte Bedienung und Überprüfung von Swing-Benutzeroberflächen
* Gleichzeitige Bedienung mehrerer Anwendungen
* Steuerung von Swing-Benutzeroberflächen auf entfernten Zielsystemen
* Steuerung von bereits eigenständig laufenden Java-Anwendungen (keine Änderung am Quell-Code notwendig, keine Rekompilierung der Anwendung nötig)
* Adressierung der Bedienelemente durch XPath
* Zugriff auf Objektebene durch Java Bridge Interface Library möglich
* Integration in die [[Expecco GUI Tests_Extension Reference|expecco GUI Tests Extension]]
* Block-Bibliothek mit Aktionen und Überprüfungen für Swing-Komponenten

=== Java SWT ===

=== JavaFX ===
Ab Java 11 ist JavaFX nicht mehr im JDK enthalten. Daher müssen Sie zusätzlich ein JavaFX SDK installieren, z.B. von [https://openjfx.io/ OpenJFX]. Kopieren Sie dann die jar-Dateien aus dem lib-Verzeichnis des JavaFX JDKs nach <code>packages\exept\expecco\plugin\javafx\lib</code> im expecco-Installationsverzeichnis.

== Funktionsweise ==

Das Interface baut eine Verbindung zur Java-VM auf und stellt Funktionen zum Lesen von Widget-Attributen, Aufnehmen von Benutzereingaben sowie zum Fernsteuern der Anwendung zur Verfügung. Außerdem werden in einer Bibliothek zusätzliche Bausteine zur Automatisierung von Tests bereitgestellt.
Im wesentlichen besteht das Java-Swing-Plugin aus zwei Teilen, der Erweiterung
für expecco und der Applikationssteuerung (Agent). Zur Steuerung der Swing-Anwendung wird ein so genannter Agent in die Java Virtual Machine der laufenden Java Anwendung geladen. Um den Agenten zu laden wird ein Java Development Kit 1.8 (JDK) oder höher benötigt. Die zu testende Anwendung kann jedoch in einer normalen Java Runtime Edition 1.8 (JRE) ausgeführt werden.

== Anforderungen ==

Auf dem Rechner auf dem die zu testende Anwendung laufen soll (lokal oder entfernt):

* [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html Java Development Kit 1.8] oder höher (zum Laden des Agents)
* [http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html Java Runtime Edition 1.8] oder höher (zur Ausführung der zu testenden Anwendung)

Auf dem expecco Rechner gelten die expecco Anforderungen.

Bitte nehmen Sie zur Kenntnis, dass sowohl der Agent als auch die zu testende Anwendung jeweils beide entweder mit 32 oder 64 Bit Java gestartet werden müssen, da ansonsten keine Verbindung möglich ist.

Aufgrund von JDK Änderungen zwischen den Java-Versionen können potentiell Versionskonflikte auftreten.

Die Kompatibilität der Versionen ist wie folgt. [[Java GUI Plugins#Fehlerbehandlung|Weitere Informationen dazu.]]

[[Datei:JavaSwing Bridge Compatibility.png|border|200px|]]

===Zugriffsberechtigungen===

Um eine Verbindung auf dem Zielsystem garantieren zu können, müssen beim Start der zu testenden Anwendung (sowie des Java-Agenten) zusätzliche Parameter mitgegeben werden.

Dabei ergeben sich zwei Möglichkeiten, dies zu tun:

* Setzen einer Umgebungsvariablen die automatisch beim Start jeder Java-Anwendung geladen wird
* Manuelle Übergabe der Parameter bei jedem Start einer Java Anwendung
* (Alternativ kann man Zugriffsrechte in den module-info.java Dateien direkt verändern, dies ist jedoch alles andere als praktikabel)

'''Bis Java 11''' sollte es ausreichen, folgende Parameter zu setzen:
:<code>-Djdk.attach.allowAttachSelf=true</code>
:<code>--illegal-access=permit</code>

Das Setzen einer Umgebungsvariable funktioniert folgendermaßen (''Am Beispiel JDK_JAVA_OPTIONS, welche bei jedem JVM Start geladen wird'') 
'''für Windows Systeme''' 
* <code>setx JDK_JAVA_OPTIONS "-Djdk.attach.allowAttachSelf=true; --illegal-access=permit"</code>
* oder über das GUI (Windowstaste + Pause). 
[[Datei:Windows Setenvironment.png|border|600px|]]
 
'''für Unix Systeme''' 
* Bash: <code>export _JAVA_OPTIONS='-Djdk.attach.allowAttachSelf=true; --illegal-access=permit'</code>
* C Shell: <code>setenv _JAVA_OPTIONS '-Djdk.attach.allowAttachSelf=true; --illegal-access=permit'</code>
 

'''Ab Java 11''' erfolgt für die Kapselung von Modulen eine striktere Trennung:

<code>--illegal-access=permit</code> wird dabei nicht mehr funktionieren, falls die Zielapplikation eine festgelegte Modulkapselung besitzt ([https://stackoverflow.com/questions/46741907/what-is-an-automatic-module Details]).
In diesem Fall müssen beim Programmstart zusätzliche Parameter angegeben werden, welche Expecco einen Zugriff auf die innewohnenden Ressourcen gewähren.
Je nach verwendeter Technologie können die benötigten Parameter variieren, weshalb Sie diese selbstständig herausfinden müssen.
<code>jdeps list-deps JARNAME.jar</code> Jdeps ist dafür ein frei verfügbares (Teil des JDK) sehr nützliches Werkzeug.
Eine kurze Übersicht der Kommandos findet man [https://doc.expecco.de/w2.x/images/0/03/Java_module_cheat_sheet.pdf hier] [https://zeroturnaround.com/rebellabs ©]

----

'''Beispiel JavaFX''':

Die Umgebungsvariable <code>PATH_TO_FX</code>, die auf das JavaFX Verzeichnis zeigt, muss gesetzt sein (Funktionsweise s.o.) und die folgenden Parameter müssen beim Start der Java Anwendung vorhanden sein:

<div class="toccolours mw-collapsible mw-collapsed">
Parameterliste (ausklappbar)
<div class="mw-collapsible-content">
*<code>--module-path "%PATH_TO_FX%" </code>

* <code>--add-modules=javafx.controls </code>
* <code>--add-modules=javafx.swing </code>
* <code>--add-modules=javafx.web </code>

* <code>--add-opens javafx.graphics/com.sun.javafx.sg.prism=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.stage=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/com.sun.javafx.stage=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene.layout=ALL-UNNAMED </code>

* <code>--add-opens javafx.controls/javafx.scene.control=ALL-UNNAMED </code>
* <code>--add-opens javafx.controls/javafx.scene.control.skin=ALL-UNNAMED </code>
* <code>--add-opens javafx.controls/javafx.scene.chart=ALL-UNNAMED </code>
* <code>--add-exports javafx.controls/com.sun.javafx.charts=ALL-UNNAMED </code>
* <code>--add-opens javafx.controls/com.sun.javafx.charts=ALL-UNNAMED </code>
* <code>--add-exports javafx.controls/com.sun.javafx.scene.control=ALL-UNNAMED </code>
* <code>--add-opens javafx.controls/com.sun.javafx.scene.control=ALL-UNNAMED </code>

* <code>--add-opens javafx.graphics/javafx.scene.image=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene.shape=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene.text=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.application=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.geometry=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene.robot=ALL-UNNAMED </code>
* <code>--add-exports javafx.graphics/com.sun.glass.ui=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/com.sun.glass.ui=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/com.sun.glass.ui.win=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene.input=ALL-UNNAMED </code>

* <code>--add-opens javafx.base/javafx.event=ALL-UNNAMED </code>
* <code>--add-exports javafx.base/com.sun.javafx.runtime=ALL-UNNAMED </code>
* <code>--add-opens javafx.base/com.sun.javafx.runtime=ALL-UNNAMED </code>

* <code>--add-exports javafx.graphics/com.sun.javafx.scene=ALL-UNNAMED </code>
* <code>--add-exports javafx.graphics/com.sun.javafx.util=ALL-UNNAMED </code>
* <code>--add-exports javafx.graphics/com.sun.javafx.scene.input=ALL-UNNAMED </code>

* <code>--add-exports javafx.web/com.sun.webkit.dom=ALL-UNNAMED</code>
</div>
</div>

Wenn Sie die Kommandozeilenoptionen nicht einzeln angeben wollen, können Sie anstatt dessen [[Datei:Java_fx_command_options.txt]] verwenden, indem sie das java Kommando aufrufen wie folgt:
java @java_fx_command_options.txt ....

Sollten Sie dennoch einen <code>java.lang.IllegalAccessError</code> erhalten, müssen Sie diese Parameter in folgender Weise erweitern:
* Fehlertext der Art <code>module <module> does not "opens <package>" to unnamed module</code>:
: <code>--add-opens <module>/<package>=ALL-UNNAMED </code>
: ''Beispiel:'' <code>module java.base does not "opens java.lang" to unnamed module</code> ''lösen Sie mit:'' <code>--add-opens java.base/java.lang=ALL-UNNAMED</code>
* Fehlertext der Art <code>cannot access class <package>.<class name> (in module <module>) because module <module> does not export <package> to unnamed module</code>:
: <code>--add-exports <module>/<package>=ALL-UNNAMED </code>
: ''Beispiel:'' <code>cannot access class com.sun.javafx.scene.input.ExtendedInputMethodRequests (in module javafx.graphics) because module javafx.graphics does not export com.sun.javafx.scene.input to unnamed module</code> ''lösen Sie mit:'' <code>--add-exports javafx.graphics/com.sun.javafx.scene.input=ALL-UNNAMED</code>

'''Hilfsprogramm Erzeugen eines CommandLine-Files (Java 11 ff.)'''

Siehe [[JavaBridgeOpenModule|Erzeugen eines CommandLine-Files für Module ab java 11]]

== Konfiguration ==
=== Installation auf dem expecco Rechner ===

Achten Sie bei der Installation von expecco darauf, dass das Java-Plugin als zu installierende Komponente ausgewählt ist.

Wird die zu testende Anwendung zur Entwicklung von Testsequenzen auf dem gleichen Rechner ausgeführt, sollte nach dem Start von expecco unter
<code>Extras → Einstellungen → Erweiterungen → Java Bridge</code> der lokale Pfad zu einem Java Development Kit 1.8 oder höher angegeben werden.

Die unbedingt erforderliche Einstellung hier ist <code>Pfad zur JDK Installation</code>, welche für die Hauptverbindung genutzt wird. <code>Pfad zur Java Installation</code> ist eine alternative Einstellung für Groovy, welches nur ein JRE benötigt. Der Java Agent wird in lokalen Verbindungen automatisch mit diesen Einstellungen gestartet.

[[Datei:JDKPfadEinstellungen.png|border|600px|]]

=== Installation auf dem Testanwendungsrechner ===

Es muss das javaBin Verzeichnis des Expecco Bridge Frameworks auf den Testrechner kopiert werden. Dieses befindet sich im expecco Installationsverzeichnis unter:

<nowiki>...\packages\exept\bridgeFramework\javaBridge\javaBin</nowiki>

Damit expecco sich verbinden kann, muss der kopierte "AgentLoader" gestartet werden.
[https://doc.expecco.de/wiki2.x/Java_GUI_Plugins#Verbindung_zu_Entfernten_Systemen Starten des "AgentLoader"]

== expecco GUI Browser ==

Der expecco GUI-Browser ist ein zusätzliches Werkzeug, welches die Möglichkeit bietet, laufende Anwendungen zu analysieren und Testsequenzen zu entwickeln. Anschließend kann man die Informationen, wie beispielsweise Namen und Eigenschaften einzelner Elemente dazu verwenden, um mit der Funktionsbibliothek Aktionen auszuführen bzw. mit einzelnen Elementen zu interagieren.

=== Verbindungsaufbau ===

Im Folgenden eine kurze Bilderstrecke, die Ihnen beim Einrichten einer Verbindung als '''Leitfaden''' dienen kann

[[Datei:JavaSwing GUI Browser.png|border|600px|]]

Zunächst wählt man über den <code>GUI Browser</code> (schwarzer Kreis) im Reiter <code>Verbinden</code> die Option <code>Java</code> (roter Kreis) aus. Im sich öffnenden Dialog kann man nun zwischen 3 Optionen wählen.

* '''Anwendung auf der lokalen Maschine starten'''
: Liefert eine bequeme Möglichkeit eine lokale Java Anwendung per Kommandozeilenbefehl zu starten.
* '''Zu einer laufenden Anwendung auf der lokalen Maschine verbinden'''
: Ermöglicht die Verbindung zu lokal laufenden Java Anwendungen. Der Java-Agent wird automatisch mit der Java-Version, die Sie in den Expecco Einstellungen festgelegt haben, gestartet.
* '''Zu einer laufenden Anwendung auf einer anderen Maschine verbinden'''
: Ermöglicht die Verbindung zu einem bereits gestarteten Java-Agenten auf einer anderen Maschine. Dieser stellt dann die Verbindung zur dort laufenden Java Anwendung her.

----

[[Datei:JavaSwing Connection Window.png|border|600px|]]

Eine Suche nach Java-Anwendungen listet uns alle laufenden Java Virtuellen Maschinen (JVMs) auf, die sich auf dem Zielsystem befinden (im Beispiel: localhost). Eine Auswahl der einzelnen Einträge listet weitere Informationen über die betreffende Anwendung auf. 

----

[[Datei:JavaSwing Connection Connected.png|border|600px|]]

Wenn eine Verbindung erfolgreich aufgebaut wurde, wird sie automatisch in die expecco Konfigurationsliste eingetragen.
Dort kann auch der GUI Aufbau der Anwendung als hierarchischer Baum eingesehen werden.
Informationen zum weiteren Vorgehen können Sie unter [[Expecco_GUI_Tests_Extension_Reference| GUI Test Referenz]].

----

[[Datei:JavaSwing Connection Reconnect.png|border|600px|]]

Geschlossene Verbindngen bleiben im GUI-Browser erhalten. Wenn die Anwendung noch läuft, können Sie die Verbindung wieder aufbauen. Machen Sie dazu einen Rechtsklick auf den Eintrag und wählen Sie im Kontextmenu den Eintrag ''Verbinden''.
Falls sich die Verbindungseinstellungen geändert haben, müssen Sie die Verbindung neu konfigurieren. Dies kann passieren, wenn Sie die Anwendung zwischenzeitlich neu gestartet haben. Bei Verwendung eines entfernten Systems gilt dies auch für den Agenten.

=== Verbindung zu Entfernten Systemen ===
[[Datei:JavaSwing Connection RemoteSetup.png|border|600px|]]

Um eine Verbindung remote zu erstellen, muss zunächst auf dem Zielrechner der Java-Agent gestartet werden.
Dazu navigieren Sie auf dem Rechner zum zuvor kopierten Verzeichnis <code>...\packages\exept\bridgeFramework\javaBridge\javaBin</code>.
Dort liegt ein Skript, welches automatisch die Java-Version in JAVA_HOME erkennt und den korrekten Agenten startet.
* Windows Nutzer starten <code>startAgentLoader.bat</code>
* UNIX Nutzer starten <code>startAgentLoader.sh</code>
Diese Skripte können über die Kommandozeile wie im Bild gezeigt mit Parametern versehen werden.
* <code>-ip <HostnameOderIP></code> gibt dem Agenten eine spezielle IP an, auf der auf eine Verbindung gewartet werden soll. Nützlich für spezifische Netzwerkmasken.
:StandardHost ist 0.0.0.0.
* <code>-port >PortNummer</code> gibt dem Agenten einen spezifischen Port an, auf dem auf Verbindungen von Expecco gewartet werden soll.
:Standardport ist 56784.
* <code>-foreground</code> der Agent wird im Konsolenfenster ausgeführt. Log-Nachrichten werden direkt im Konsolenfenster angezeigt. Man kann den Agenten über das Konsolenfenster beenden. Ansonsten wird der Agent in einem separaten Hintergrundprozess ausgeführt.

=== Warnhinweise ===
[[Datei:JavaSwing Connection Warnings.png|border|600px|]]
 
Sollten bei den Anwendungen in dieser Liste Probleme auftreten wie im oben stehenden Bild zu sehen ist,
liefert der Verbindungsdialog automatisch einen Lösungsvorschlag. Wenn der auftretende Fehler eine Verbindung unmöglich machen würde, wird der entsprechende Eintrag automatisch als ungültig markiert.

Folgende Fehlermeldungen können auftreten und sind einfach zu beheben:
::{|
|style="width: 22%;"|JAVA VERSION MISMATCH
|Wie im Bild zu sehen, kann es zu Java Versionskonflikten zwischen dem Agenten und der Anwendung kommen. In diesem Fall ist es am einfachsten die Expecco Einstellungen für Java Bridge anzupassen. Eine Remote Verbindung müsste das Programm stattdessen manuell mit der gewollten Java Version starten. Der Java Agent, wenn über das <code>startAgentLoader</code> skript aufgerufen, wählt die Version Anhand von <code>JAVA_HOME</code> auf dem remote System
|-
|32 BIT - 64 BIT KONFLIKT
|32 und 64 Bit Versionen von Java sind nicht miteinander Kompatibel. Sowohl der Agent als auch die Anwendung müssen mit der selben "Bit Version" von Java gestartet werden.
|-
|UNABLE TO DETERMINE VERSION
|Der Agent kann nicht feststellen, welche Java Version die Anwendung nutzt. Eine Verbindung ist eventuell möglich, es kann aber potentiell ein Versionskonflikt auftreten.
|}
:

== Technologieübergreifende Verbindungen ==
Falls eine Anwendung mehrere Java-Technologien verwendet, müssen Sie nur eine Verbindung aufbauen und dann die Bausteine aus der Library entsprechend der Technologie des anzusprechenden Elements verwenden.

=== Eingebettetes JavaFX in Java Swing ===
Ist JavaFX in eine Swing-Anwendung eingebettet, enthält diese ein Element JFXPanel. Im GUI-Browser werden die JavaFX-Elemente unterhalb von diesem Panel angezeigt. Damit die FX-Bausteine diese eingebetteten FX-Elemente finden, muss zu Beginn der Baustein ''Set FX Context To Panel'' aus der Swing-Library mit dem Pfad zum JFXPanel ausgeführt werden.

=== WebView in JavaFX ===
Ist ein WebView in JavaFX eingebunden, so werden dessen Elemente im GUI-Browser unterhalb des WebView-Elements angezeigt. Für diese Elemente gibt es eigene Bausteine in der JavaFX-Library, die im Ordner ''Embedded WebView'' zusammengefasst sind. Damit die Elemente im Test gefunden werden können, muss zuvor der Baustein ''Set WebView Context'' auf das Element WebView ausgeführt werden. Dieser Kontext ist gültig, bis sich die vom WebView dargestellte Seite ändert. In diesem Fall müssen Sie den Kontext erneut setzen, um auf die neuen Elemente zuzugreifen.

=== Eingebettetes Java Swing in JavaFX ===
Ist Java Swing in eine JavaFX-Anwendung eingebettet, enthält diese ein Element SwingNode. Im GUI-Browser wird dessen Inhalt bisher noch parallel zum FX-Inhalt angezeigt. Die Bausteine der Swing-Library können direkt mit diesen Elementen verwendet werden.

== JavaSwingLibrary ==

== Example ==

== FAQ ==


* '''Der Baum im GUI-Browsers zeigt nicht alle Elemente meiner Applikation''' 
:Eine Applikation besteht aus vielen verschiedenen Elementen. Manche davon sind nicht interaktiv, das heißt sie sind für den Anwender nicht direkt sichtbar und dienen lediglich der Formatierung, wie beispielsweise Panels. Das Vorhandensein solcher Elemente führt dazu, dass der Baum sehr groß und tief werden kann. Da diese Elemente in der Regel für die Automatisierung uninteressant sind, werden sie in expecco standardmäßig ausgeblendet.
:Wenn Sie in Ihrem Fall auf eines dieser Elemente zugreifen wollen oder es für das Erstellen eines eindeutigen Pfades brauchen, können Sie dieses Verhalten ändern. In der JavaSwingLibrary gibt es dafür den Baustein ''Set Skip Mode''. Dabei sind vier Modi auswählbar:
::{|
|INTERACTIVE
|nur interaktive Elemente einsammeln
|-
|ALL
|alle Elemente einsammeln
|-
|INTERACTIVE_HYBRID
|wie INTERACTIVE, aber mit dem Fallback zu ALL wenn ein Pfad nicht aufgelöst werden kann
|-
|ALL_HYBRID
|wie ALL, aber mit dem Fallback auf INTERACTIVE wenn ein Pfad nicht aufgelöst werden kann
|}
:Durch das Ausführen des Bausteins ändert sich das Verhalten für die aktuelle Verbindung. Es bezieht sich sowohl darauf, was im Baum angezeigt wird, als auch, wie mit den Pfaden an den Bausteinen umgegangen wird. Ab expecco 19.1 ist die Standardeinstellung ALL_HYBRID und in früheren Versionen INTERACTIVE.

*'''Ich kann mich nicht verbinden, aber alle Einstellungen stimmen'''
:Auch wenn dies generell nicht passieren sollte, hier ein paar Aspekte, die Einfluss auf die Verbindung nehmen können.
::{|
|FIREWALL
|Die Firewall kann das Kommunizieren des Java Agenten mit der Anwendung stören. Entweder man richtet eine Ausnahmeregel für den Agenten ein oder aber man deaktiviert die Firewall für die Dauer des Tests.
|-
|SOCKET BELEGT
|Es kann vorkommen, besonders beim Debuggen, dass eine vorherige Instanz eines Java Agenten nicht korrekt geschlossen wurde. Das kann dazu führen, dass dieser den Socket belegt und andere Verbindungen abweist. Über <code>Extras => Fehleranalyse => Alle Bridgeverbindung schließen / Alle Socketverbindungen schließen</code> werden vorherige Instanzen entfernt. Bitte beachten, dass damit auch alle anderen bestehenden (lokalen) Expecco Verbindungen geschlossen werden. Im Fall einer Remote-Verbindung sollte ein Neustart des Agenten und evtl. auch der Anwendung Abhilfe schaffen.
|}