Skip to content

Commit 4aa66d9

Browse files
yumaokayumaoka
authored
Merge pull request #60 from jugu/master
Added integration tests for gp-maven-plugin
2 parents a2f3687 + 31511e2 commit 4aa66d9

32 files changed

Lines changed: 1055 additions & 22 deletions

File tree

‎gp-ant-task/README.md‎

Lines changed: 102 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@
2323
* [Tasks](#TOC-Usage-Tasks)
2424
* [Specifying Globalization Pipeline Service Credentials](#TOC-Usage-Credentials)
2525
* [Basic Use Case](#TOC-Usage-Basic)
26-
* [Example](#Example)
26+
* [Task Parameters in build.xml](#TOC-Parameters)
27+
* [Example](#TOC-Usage-Example)
2728

2829
---
2930
## <a name="TOC-Overview"></a>Overview
@@ -51,7 +52,7 @@ from the official [release page](https://github.com/IBM-Bluemix/gp-java-tools/re
5152
2. Set up name space for the Globalization Pipleline tasks and task definition
5253
as below in your Ant build.xml as below.
5354

54-
```
55+
```xml
5556
<?xml version="1.0" encoding="utf-8" ?>
5657
<project name="My Project" xmlns:gp="antlib:com.ibm.g11n.pipeline.ant">
5758

@@ -99,7 +100,8 @@ your Globalization Pipeline service instance.
99100

100101
In your Ant build.xml, specify the JSON file in **credentialsJson** attribute in
101102
each Globalization Pipeline Ant task as below:
102-
```
103+
104+
```xml
103105
<target name="upload-resources">
104106
<gp:upload credentialsJson= "gpcreds.json" sourceDir="src/main/resources"/>
105107
</target>
@@ -110,7 +112,7 @@ each Globalization Pipeline Ant task as below:
110112
The service credentials can be also embedded in `build.xml` using `<credentials>` tag
111113
as below.
112114

113-
```
115+
```xml
114116
<target name="upload-resources">
115117
<gp:upload sourceDir="src/main/resources">
116118
<credentials url="https://gp-rest.ng.bluemix.net/translate/rest"
@@ -126,7 +128,7 @@ used by Globalization Pipeline service instance.
126128
### <a name="TOC-Usage-Basic"></a>Basic Use Case
127129

128130
**build.xml** below illustrates basic use cases of the tant tasks:
129-
```
131+
```xml
130132
<?xml version="1.0" encoding="utf-8"?>
131133
<project name="Example Project" xmlns:gp="antlib:com.ibm.g11n.pipeline.ant">
132134

@@ -141,8 +143,8 @@ used by Globalization Pipeline service instance.
141143
<target name="upload-resources">
142144
<gp:upload credentialsJson= "${gp.credentials}" sourceDir="src/main/resources" />
143145
</target>
144-
145-
<!-- Downloads translated .properties files from the Globalization Pipeline services intances to outputDir ->
146+
147+
<!-- Downloads translated .properties files from the Globalization Pipeline services intances to outputDir -->
146148
<target name="download-translations">
147149
<gp:download credentialsJson="${gp.credentials}" sourceDir="src/main/resources" outputDir="target/classes" />
148150
</target>
@@ -191,6 +193,99 @@ standard build output directory (`target/classes`) (*outputDir* attribute) with
191193
as `Messages_fr.properties` for French. This operation is done for all available
192194
target languages in the Globalization Pipeline bundle.
193195

196+
### <a name="TOC-Parameters"></a>Task Parameters
197+
198+
### upload task
199+
The upload task should be configured using `gp:upload` task definition. The attributes and nested elements
200+
of `gp:upload` are described below:
201+
202+
|Attribute|Description|Required|
203+
| ------- | --------- | ------ |
204+
|credentialsJson| Specifies the pathname of Globalization Pipeline Instance credentials file|Yes (if the nested element `credentials` is not used)|
205+
|sourceDir| Specifies the pathname for the location where all the relevant bundle files to be uploaded are kept|Yes|
206+
##### Nested elements for upload task
207+
##### credentials (optional, can be omitted if credentialsJson is specified.)
208+
|Attribute|Description|Required|
209+
| ------- | --------- | ------ |
210+
|url| Specifies the instance url | Yes |
211+
|userId| Specifies the userId | Yes |
212+
|password| Specifies the password | Yes |
213+
|instanceId| Specifies the instance id | Yes |
214+
215+
##### targetLanguage (optional)
216+
|Attribute|Description|Required|
217+
| ------- | --------- | ------ |
218+
|lang | Specifies the MT language which the uploaded file should be translated to| Yes |
219+
220+
##### bundleSet (optional)
221+
|Attribute|Description|Required|
222+
| ------- | --------- | ------ |
223+
| type | Type of resource bundle file (JSON, JAVA (properties), AMDJS, ...)| No, defaults to JAVA properties file format|
224+
|sourceLanguage|Specifies BCP 47 language tag for the language used in the source bundles|No, The default language of `en` is used|
225+
|languageIdStyle| Specifies one of following keywords to configure the rule for composing language ID used for output resource bundle file or path name.<ul><li><b>BCP47_UNDERSCORE</b> BCP 47 language tag, replacing '-' with '_'. For example, zh_Hant for Traditional Chinese.</li><li><b>BCP47</b> BCP 47 language tag itself. For example, zh-Hant for Traditional Chinese </li></ul>| No, The default value is BCP47_UNDERSCORE|
226+
227+
##### targetLanguage (nested within bundleSet, optional too)
228+
|Attribute|Description|Required|
229+
| ------- | --------- | ------ |
230+
|lang | Specifies the MT language which the uploaded file should be translated to| Yes |
231+
232+
##### fileset (nested within bundleSet, required if bundleSet is used)
233+
|Attribute|Description|Required|
234+
| ------- | --------- | ------ |
235+
|dir| Specifies the source directory location for the bundleSet to be used as reference | Yes |
236+
|includes| Specifies the file pattern that needs to be included for uploading|No, but recommended|
237+
|excludes| Specifies the file pattern that needs to be excluded for uploading|No|
238+
239+
### download task
240+
The download task should be configured using `gp:download` task definition. The attributes and nested elements
241+
of `gp:download` are described below:
242+
243+
|Attribute|Description|Required|
244+
| ------- | --------- | ------ |
245+
|credentialsJson| Specifies the pathname of Globalization Pipeline Instance credentials file|Yes (if the nested element `credentials` is not used)|
246+
|sourceDir| Specifies the pathname for the location where all the relevant bundle files to be referenced for download are kept|Yes|
247+
|outputDir| Specifies the pathname for the location where all the resource bundle files should be downloaded|No, defaults to `target/classes` directory|
248+
##### Nested elements for download task
249+
##### credentials (optional, can be omitted if credentialsJson is specified.)
250+
|Attribute|Description|Required|
251+
| ------- | --------- | ------ |
252+
|url| Specifies the instance url | Yes |
253+
|userId| Specifies the userId | Yes |
254+
|password| Specifies the password | Yes |
255+
|instanceId| Specifies the instance id | Yes |
256+
257+
##### targetLanguage (optional)
258+
|Attribute|Description|Required|
259+
| ------- | --------- | ------ |
260+
|lang | Specifies the MT language which the uploaded file should be translated to| Yes |
261+
262+
##### bundleSet (optional)
263+
|Attribute|Description|Required|
264+
| ------- | --------- | ------ |
265+
| type | Type of resource bundle file (JSON, JAVA (properties), AMDJS, ...)| No, defaults to JAVA properties file format|
266+
|sourceLanguage|Specifies BCP 47 language tag for the language used in the source bundles|No, The default language of `en` is used|
267+
|languageIdStyle| Specifies one of following keywords to configure the rule for composing language ID used for output resource bundle file or path name.<ul><li><b>BCP47_UNDERSCORE</b> BCP 47 language tag, replacing '-' with '_'. For example, zh_Hant for Traditional Chinese.</li><li><b>BCP47</b> BCP 47 language tag itself. For example, zh-Hant for Traditional Chinese </li></ul>| No, The default value is BCP47_UNDERSCORE|
268+
|outputDir|Specifies the output base directory for this bundleSet|No, If not specified, `outputDir` specified at `gp:download` level is used|
269+
|outputContentOption|Specifies one of following keywords to control how download goal generates the contents of translated resource bundle files.<ul><li><b>MERGE_TO_SOURCE</b> Duplicates the contents of the source bundle and replaces only translated resource strings. This option might not be implemented by some format types. In this case, TRANSLATED_WITH_FALLBACK is used instead.</li><li><b>TRANSLATED_WITH_FALLBACK</b> Emits only resource strings (with a simple header if applicable). When translated string value is not available, the value in the source language is used.</li><li><b>TRANSLATED_ONLY</b> Emits only resource strings (with a simple header if applicable). When translated string value is not available, do not include the key in the output.</li><li><b>MERGE_REVIEWED_TO_SOURCE</b> Duplicate the contents of the source bundle and replaces only translated resource strings marked as reviewed. This option might not be implemented by some format types. In this case, REVIEWED_WITH_FALLBACK is used instead.</li><li><b>REVIEWED_WITH_FALLBACK</b> Emits only resource strings marked as reviewed. When translated string value is not available, or not marked as reviewed, the value in the source language is used.</li><li><b>REVIEWED_ONLY</b> Emits only resource strings marked as reviewed. When translated string value is not available, or translated not marked as reviewed, do not include the key in the output.|No, The default value is MERGE_TO_SOURCE.|
270+
|bundleLayout|Specifies one of following keywords to control output file name or path in download goal.<ul><li><b>LANGUAGE_SUFFIX</b> In the same directory with the source bundle file, with extra language suffix. For example, if the source bundle file is com/ibm/g11n/MyMessages.properties, then the French version will be com/ibm/g11n/MyMessages_fr.properties.</li><li><b>LANGUAGE_SUBDIR</b> In a language sub-directory under the directory where the source bundle file is placed. For example, if the source bundle file is res/MyMessages.json, then the French version will be res/fr/MyMessages.json.</li><li><b>LANGUAGE_DIR</b> In a language directory at the same level with the source bundle file. For example, if the source bundle file is com/ibm/g11n/en/MyMessages.properties, then the French version will be com/ibm/g11n/fr/MyMessages.properties.</li>|No, The default value is LANGUAGE_SUFFIX.|
271+
272+
##### targetLanguage (nested within bundleSet, optional too)
273+
|Attribute|Description|Required|
274+
| ------- | --------- | ------ |
275+
|lang | Specifies the MT language which the uploaded file should be translated to| Yes |
276+
277+
##### languageMap (nested within bundleSet, optional)
278+
|Attribute|Description|Required|
279+
| ------- | --------- | ------ |
280+
|from | Specifies the language code used in bundle files/directories which needs to be downloaded | Yes|
281+
|to | Specifies the language code to be used when naming the downloaded file/directory|Yes|
282+
283+
##### fileset (nested within bundleSet, required if bundleSet is used)
284+
|Attribute|Description|Required|
285+
| ------- | --------- | ------ |
286+
|dir| Specifies the source directory location for the bundleSet to be used as reference | Yes |
287+
|includes| Specifies the file pattern that needs to be included for reference when downloading|No, but recommended|
288+
|excludes| Specifies the file pattern that needs to be excluded for reference|No|
194289

195290
### <a name="TOC-Usage-Example"></a>Example
196291

‎gp-maven-plugin/integration-test-README.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
## gp-maven-plugin Integration Tests
2+
3+
To test existing features of gp-maven-plugin, integration tests have been added. New integration tests can be added
4+
to test more advanced cases/new features as per need by following the template of existing integration tests. To execute the integration tests:
5+
6+
* Make sure that following profile is added to the **src/pom.xml**
7+
```
8+
<profile>
9+
<id>run-its</id>
10+
<activation>
11+
<property>
12+
<name>skipTests</name>
13+
<value>!true</value>
14+
</property>
15+
</activation>
16+
<build>
17+
<plugins>
18+
<plugin>
19+
<groupId>org.apache.maven.plugins</groupId>
20+
<artifactId>maven-invoker-plugin</artifactId>
21+
<version>2.0.0</version>
22+
<configuration>
23+
<debug>true</debug>
24+
<addTestClassPath>true</addTestClassPath>
25+
<cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
26+
<setupIncludes>
27+
<setupInclude>setup/pom.xml</setupInclude>
28+
</setupIncludes>
29+
<pomIncludes>
30+
<pomInclude>*/pom.xml</pomInclude>
31+
</pomIncludes>
32+
<preBuildHookScript>setup</preBuildHookScript>
33+
<postBuildHookScript>verify</postBuildHookScript>
34+
<localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>
35+
<settingsFile>src/it/settings.xml</settingsFile>
36+
</configuration>
37+
<executions>
38+
<execution>
39+
<id>integration-test</id>
40+
<goals>
41+
<goal>run</goal>
42+
</goals>
43+
</execution>
44+
</executions>
45+
</plugin>
46+
</plugins>
47+
</build>
48+
</profile>
49+
```
50+
* Then execute ```$ mvn integration-test ```
51+
52+
The result of this run will show which tests passed/failed
53+
54+
## Integration Test Directory Structure
55+
56+
All the integration tests are organized into folders under **src/it** directory. The directory structure is shown below:
57+
58+
```
59+
src
60+
├── it
61+
| ├── settings.xml
62+
| ├── t1-basic-upload-fail
63+
| ├── t2-basic-upload-success
64+
| ├── t3-basic-download-fail
65+
| └── t4-basic-download-success
66+
| ├── src/main/resources/com/bundle1
67+
| | ├── ResourceBundle.properties
68+
| | └── ResourceBundle.json
69+
| ├── invoker.properties
70+
| ├── pom.xml
71+
| ├── setup.properties
72+
| ├── setup.groovy
73+
| └── verify.groovy
74+
└── test
75+
└── java
76+
└── com
77+
└── ibm
78+
└── g11n
79+
└── pipeline
80+
└── maven
81+
├── CredentialsExtended.java
82+
├── GPInstance.java
83+
└── ITTools.java
84+
```
85+
86+
Let's take the example of the integration test **_t4-basic-download-success_**
87+
88+
This integration test ensures that the download of json resource bundle files should succeed
89+
90+
The **_t4-basic-download-success_** test contains following files:
91+
92+
####invoker.properties
93+
94+
> This file contains the properties for the integration test invoker.
95+
```
96+
invoker.name=basic upload test which should succeed
97+
invoker.goals=${project.groupId}:${project.artifactId}:${project.version}:upload integration-test
98+
invoker.debug=false
99+
invoker.buildResult=success
100+
invoker.mavenOpts=-Dgp.credentials.json=credentials.json
101+
```
102+
> The ```invoker.goals``` specifies the gp-maven-plugin action that needs to be triggered as part of integration test
103+
104+
> The ```invoker.buildResult``` attribute specifies the expected result of the test (_success_/_failure_)
105+
106+
> The ```invoker.mavenOpts``` specifies the credentials file which needs to be used before triggering the goal
107+
108+
> The file is **mandatory**
109+
110+
####pom.xml
111+
112+
> This file specifies the plugin execution goals as desired.
113+
```
114+
<plugin>
115+
<groupId>@project.groupId@</groupId>
116+
<artifactId>@project.artifactId@</artifactId>
117+
<version>@project.version@</version>
118+
<executions>
119+
<execution>
120+
<goals>
121+
<goal>download</goal>
122+
</goals>
123+
</execution>
124+
</executions>
125+
<configuration>
126+
<bundleSets>
127+
<bundleSet>
128+
<sourceFiles>
129+
<directory>src/main/resources</directory>
130+
<includes>
131+
<include>**/*.json</include>
132+
</includes>
133+
</sourceFiles>
134+
<type>JSON</type>
135+
</bundleSet>
136+
</bundleSets>
137+
</configuration>
138+
</plugin>
139+
```
140+
> The above shown plugin execution configuration implies that the gp-maven-plugin should execute download as part of the maven build.
141+
142+
> The integration test should download all the ```json``` files from globalization pipeline instance as per the bundles
143+
located in the ```src/main/resources``` and put all the downloaded files and organize them in the default output location
144+
of ```target/classes```
145+
146+
> The file is **mandatory** but can omit plugin configuration if not required for the integration test
147+
148+
####setup.groovy
149+
150+
> This is the prebuild hook script as configured in the ```src/pom.xml```.
151+
152+
> This speficies the setup activities that need to be performed before executing the build for the integration test
153+
154+
> For this test, the script creates a ```credentials.json``` file which contains credentials of a shortlived globalization
155+
pipeline instance for integration test purposes
156+
157+
> The script makes use of methods from ```ITTools.java```. This was made possible because ```<addTestClassPath>true</addTestClasPath>```
158+
was added to **src/pom.xml** as part of ```maven-invoker-plugin``` configuration
159+
160+
> This is **optional** if there is no setup required for a particular integration test
161+
162+
####verify.groovy
163+
164+
> This is the postbuild hook script as configured in the ```src/pom.xml```
165+
166+
> This specifies the verification activities that needs to be performed post build (as part of integration test),
167+
to make sure that the build gave the results as expected.
168+
169+
> This is **optional** if there are no verification activities that need to be performed post build (integration-test)
170+
171+
####setup.properties
172+
173+
> This file is **optional** and is basically used here to help with build setup as implemented in ```setup.groovy``` script.
174+
175+
####src/main/resources/com/bundle1/
176+
177+
> This directory and its content are relevant to this particular integration test only.
178+
179+
##Invoking the integration test
180+
To just execute ```t4-basic-download-success``` test following command can be issued
181+
182+
```$ mvn integration-test -Dinvoker.test=t4-basic-download-success```
183+
184+
* As the test is executed, first the repository is cloned to a local repository (as specified in **src/pom.xml**)
185+
186+
* All the dependency artifacts are downloaded to the local-repo
187+
188+
* The prebuild script is then run to prepare setup before starting the build. For this test, the script generates ```credentials.json```
189+
190+
* The invoker goals are then executed (using the ```invoker.mavenOpts``` if supplied).
191+
For this test, first the ```upload``` goal is triggered and then ```download```
192+
193+
* The postbuild script then runs to verify that the build was successful with desired output.
194+
For this test, the downloaded files are examined to verify the number of files and also the number of translated keys per file.
195+
196+
197+
198+

0 commit comments

Comments
 (0)