Setting up Jenkins pipeline

Installing the Jenkins pipeline template

The following steps install the Jenkins pipeline template ATP-TemplateRunAutomatedTests. This pipeline will subsequently be duplicated then configured to execute your automated tests on your Sage X3 test environment.

  1. Open your browser.
  2. Go to http://[Jenkins_hostname]:[jenkins_port]/jnlpJars/jenkins-cli.jar, where [Jenkins_hostname]:[jenkins_port] is your Jenkins URL.
  3. Note - information A jenkins-cli.jar file is downloaded.
  4. Create a ATPJenkinsPipelineInstall folder in your Documents folder.
  5. Copy the Jenkins-cli.jar file to the ATPJenkinsPipelineInstall folder.
  6. Copy the ATP-TemplateRunAutomatedTests.xml file to the ATPJenkinsPipelineInstall folder.
  7. Note - information The ATP-TemplateRunAutomatedTests.xml file is in the atp-x.x.x-win zipped (compressed) file you downloaded to the 02-JenkinsPipeline folder.

  8. Open a new Windows PowerShell session in administrator mode.

  9. Change to the ATPJenkinsPipelineInstall directory.
  10. Enter the following command, replacing:
    1. [jenkins_account] with your Jenkins administrator account.
    2. [jenkins_password] with your Jenkins administrator password.
    3. [Jenkins_hostname]:[jenkins_port] with your Jenkins URL and port.

    type ATP-TemplateRunAutomatedTests.xml | java -jar jenkins-cli.jar -s http://[jenkins_account]:[jenkins_password]@[Jenkins_hostname]:[jenkins_port]/ create-job ATP-TemplateRunAutomatedTests

Note - successThe Jenkins Pipeline template ATP-TemplateRunAutomatedTests has been imported.



Creating your ATP-RunAutomatedTests pipeline

This section describes how to create your ATP-RunAutomatedTests pipeline from the ATP-TemplateRunAutomatedTests pipeline.

Note - warningDo not use the ATP-TemplateRunAutomatedTests template pipeline directly.
  1. Go to the Jenkins home page.
  2. Click New Item.
  3. Enter an item name: Type ATP-RunAutomatedTests. ATP-RunAutomatedTests is the name for your new pipeline.
  4. Select Pipeline.
  5. Copy from: Set to ATP-TemplateRunAutomatedTests.
  6. Click OK, then Apply, then Save.
  7. Return to the Jenkins home page.
  8. Note - successThe Jenkins home page displays two pipelines - your new ATP-RunAutomatedTests pipeline and the ATP-TemplateRunAutomatedTests template pipeline.

  9. Approve pipeline to be executed by Jenkins:
    1. Go to the Jenkins home page
    2. Go to manage Jenkins > In-process Script approval
    3. Approve the script related to ATP-TemplateRunAutomatedTests pipeline, so the pipeline can be executed.

Configuring your ATP-RunAutomatedTests pipeline

This section describes how to configure your ATP-RunAutomatedTests pipeline to execute the automated tests on your Sage X3 Test environment that you have pushed on GitHub, or on your Jenkins server.

Note - informationATP-RunAutomatedTests is the pipeline you created from the Jenkins pipeline template ATP-TemplateRunAutomatedTests.
  1. Check that you are connected as an administrator user.
  2. Go to the Jenkins home page.
  3. Click ATP-RunAutomatedTests.
  4. Click Configure.

  1. Configure the following parameters:
  2. UpdateATPX3: This parameter is for setting up the update of the Sage X3 Automated Test Platform Library on your ATP-RunAutomatedTests pipeline.

    • By default, the UpdateATPX3 parameter is deactivated and the Install/Update ATP stage is skipped. Sage recommends leaving it inactive by default and activating it only when you need to update the Sage X3 Automated Test Platform Library on your ATP-RunAutomatedTests pipeline.

    • If you activate the UpdateATPX3 parameter, Jenkins will install the latest Sage X3 Automated Test Platform Library version.

    • When you run your ATP-RunAutomatedTests pipeline for the first time, the Sage X3 Automated Test Platform Library is installed regardless of the value set for the UpdateATPX3 parameter.

    • You can check the install or update status of the Sage X3 Automated Test Platform Library in the console output of your ATP-RunAutomatedTests pipeline for the specific build executed during the update.

      Note - informationMake sure that your ATP-RunAutomatedTests pipeline has been updated to the latest version before activating the UpdateATPX3 parameter.
      Follow this procedure to update your ATP-RunAutomatedTests pipeline.

    ATPInstallerPath:

    • Note: from version 3.2.2 and above Sage X3 Automated Test Platform library is not downloaded anymore from Nexus repository.

    • Prior to install or update ATP, the ATP Jenkins installer containing the new version of ATP Library has to be copied on the Jenkins server so the pipeline can extract the new version of ATP and update your ATP-RunAutomatedTests pipeline.

    • Copy the ATP Jenkins installer sagex3atp-jenkins-setup-M.m.p.jar provided in atp-M.m.p-win zip (contained in 02-JenkinsPipelines folder) on your Jenkins server.

    • In ATPInstallPath parameter: indicate the path where ATP Jenkins Installer has been copied: (e.g c:\ATP\sagex3atp-jenkins-setup-M.m.p.jar)

    • Note - warning

      If your ATP-RunAutomatedTests pipeline is executed on a Jenkins slave:

      • The Jenkins installer has to be copied on the Jenkins slave.

      • The path to indicate is the path where the installer has been copied on the Jenkins slave.

    CUCUMBER_BASE_URL: The URL for the Sage X3 test environment. This parameter is mandatory.

    CUCUMBER_TAGS: This parameter filters for the automated tests which are defined with a specific tag or a combination of tags. To filter for multiple automated tests, each test must be separated using the "and" / "or" condition. This parameter is optional.

    Note - tipAll automated tests defined in the FeatureFolders parameter are executed if you leave this parameter blank.

    FEATURE_TO_RUN: This parameter filters for the specific automated tests to execute. To filter for multiple automated tests, each test must be separated using a carriage return. This parameter is optional.

    Note - tipAll automated tests defined in the FeatureFolders parameter are executed if you leave this parameter blank.

    loginUserName: Enter the required X3 user to execute the automated tests on the applicative folder of your Sage X3 test environment. This parameter is mandatory.

    loginPassword: Enter the required X3 user password to execute the automated tests on your Sage X3 test environment. This parameter is mandatory.

    loginUserRootName: Enter the required X3 user to connect to the X3 root folder of your Sage X3 test environment. This parameter is optional and only needs to be defined if you have automated tests requiring connection to the X3 root folder of your Sage X3 test environment.

    loginUserRootPassword: Enter the required X3 user password to connect to the X3 root folder of your Sage X3 test environment. This parameter is optional and only needs to be defined if you have automated tests requiring connection to the X3 root folder of your Sage X3 test environment.

    loginType: You must define this parameter for Sage X3 Automated Test Platform to use the correct authentication method to connect to the Sage X3 test environment. Set to one of the following:

    • basic - For a basic connection.
    • Sageid - For a Sageid connection (when Sageid mode is defined and the loginUserName parameter corresponds to the email address used for your SageID account).

    endpointRoot: Enter the endpoint description of the X3 root folder of your Sage X3 test environment. This parameter is optional and only needs to be defined if you have automated tests requiring connection to the X3 root folder of your Sage X3 test environment.

    endPointName1: The primary endpoint description for your test folder that the automated tests will select when executing the test. This parameter is mandatory.

    endPointName2: The secondary endpoint description for your test folder that the automated tests will select when executing the test. This parameter is mandatory if it is used in your automated tests (feature file).

    MAX_INSTANCES: The value of this parameter must be in the range 1 - 4.

    • When MAX_INSTANCES = 1, the automated tests are executed sequentially one after the other.

    • When MAX_INSTANCES > 1, the automated tests are executed in parallel, for up to four tests at the same time.

    Note - warningRefer to the Executing test in parallel chapter for recommendations on how to execute tests in parallel.

    COPY_FEATURES_FROM: This parameter defines where the feature files are retrieved from. Set to one of the following:

    • None - The Jenkins Workspace directory is not updated. The folder path or Git repository URL to copy the features from are ignored.

    • Git - The feature files are downloaded from the GitHub repository defined in the parameter COPY_FROM_FOLDER, then copied into the Jenkins pipeline Workspace to be executed.

    • Folder - This method is useful if you are not using GitHub. The feature files are downloaded from the folder path defined in the parameter COPY_FROM_FOLDER, then copied into the Jenkins pipeline Workspace to be executed.

    COPY_FROM_FOLDER:

    • If COPY_FEATURES_FROM = Git, COPY_FROM_FOLDER must be set to the following (the separator character is a semicolon (";"):

      Git URL;Branch=branch name;SparsePath=directory path

      Where:

      Git URL = The URL for your GitHub repository. This URL is mandatory.

      Branch=branch name = A specific Git branch to check out. This information is optional. If the Branch parameter is not defined, by default the master branch is checked out.

      SparsePath=directory path = A specific file or folder in the Git repository to check out. This information is optional. If the SparcePath parameter is not defined, by default all files and "directories" of the GitHub repositories are checked out.

    • If COPY_FEATURES_FROM = Folder, COPY_FROM_FOLDER will be the local path for the Jenkins server, where the feature files are copied by the user.

    FeatureFolders: Defines the relative path to the feature files or folders containing them. Therefore, depending on which path you define in the parameter COPY_FEATURES_FROM, the parameter FeatureFolders will have to be defined accordingly, with or without the root folder (for example, ATP). To execute the features in multiple directories, each directory must be separated using a carriage return.

    When Jenkins pipeline is executed, the feature files downloaded from GitHub or from the Jenkins server are temporally copied into the current pipeline workspace.


    PREREQUISITE_SCRIPT_PATH: Defines the path of the prerequisite automated tests to be executed before the automated tests selected via the FeatureFolders parameter are executed. This parameter is optional.

    When Jenkins pipeline is executed, the feature files downloaded from GitHub or from the Jenkins server are temporally copied into the current pipeline workspace.


    PREREQUISITE_SCRIPT_TAGS: This parameter filters for the prerequisite automated tests which are defined with a specific tag or a combination of tags. To filter for multiple automated tests, each test must be separated using the "and" / "or" condition. This parameter is optional.

    Note - tipAll prerequisite automated tests defined in the PREREQUISITE_SCRIPT_PATH parameter are executed if you leave this parameter blank.

    downloadFolder: Default path where files and reports are generated by Sage X3

    userStoredValuesFile: Define the path of the user-stored-values file that will be loaded before each test is executed. This parameter is optional.

    You should also push on the Jenkins server the user-stored-values file that you use with Sage X3 Automated Test Platform on your local machine. For Jenkins, the library is contained in the Jenkins workspace of the required pipeline.

    For example, for the Jenkins service used to install Jenkins, the Sage X3 Automated Test library is installed on the ATP-RunAutomatedTests Jenkins pipeline workspace after the ATP-RunAutomatedTests Jenkins pipeline has been executed at least once.

    At the beginning of the ATP-RunAutomatedTests Jenkins pipeline execution, if the userStoredValuesFile parameter contains an incorrect path, no feature will be executed. The execution will directly stop at the Check user Stored Values stage. No Allure report is generated.

    To learn more about using user stored values in your feature file, refer to the related documentation.

    Timeout:

    • timeout parameter indicates how long the robot should wait before returning an error when the element could not be found, the state of the element is incorrect, or the actual value found is different from the expected one.

    • Parameter default value: 10000 ms.

    • timeout parameter must not been set with a value below 10000 ms.

    • timeout parameter can’t exceed timeoutCucumber parameter.

    timeoutLocks:

    • timeoutLocks parameter indicates how long the robot can wait when the following step definition is executed: "the user adds the lock entry" and before returning a functional error message to the user.

    • Parameter default value: 240000 ms.

    • Default value when the parameter is not defined: 240000 ms.

    • timeoutLocks parameter can’t exceed timeoutCucumber parameter.

    timeoutPrint:

    • timeoutPrint parameter indicates how long the robot can wait when the following step definition is executed: "the user waits for a report printout with message" and before returning an error message to the user.

    • Parameter default value: 120000 ms.

    • Default value when the parameter is not defined: 120000 ms.

    • timeoutPrint parameter can’t exceed timeoutCucumber parameter.

    timeoutWaitfor:

    • timeoutWaitfor parameters indicates how long the robot can wait for Sage X3 or Sage X3 Warehousing feedbacks (e.g screen validation, page loading, open a function etc..) before returning a functional error message to the user.

    • Parameter default value: 200000 ms.

    • Default value when the parameter is not defined: 200000 ms.

    • timeoutWaitfor parameter can’t exceed timeoutCucumber parameter.

    timeoutCucumber:

    • timeoutCucumber parameters indicates the maximum time the robot can wait before returning a timeout error message to the user.

    • Parameter default value: 300000 ms.

    • Default value when the parameter is not defined: 300000 ms.

    allurePDFPrint:

    • When this parameter is activated, the allure report is also printed as a pdf document

    allurePDFName:

    • name of the allure pdf document

    • space are not allowed.

    allurePDFPath:

    • path where the allure pdf document is generated

    • e.g. c:\atp\myreport.

    • If you need to access a shared directory create a Symbolic Link between the Jenkins server and the shared directory.

      • Ms command:

        mklink /D C:[Name of folder] [network share folder path]

      • Powershell

        New-Item -Path C:[Name of folder] -ItemType SymbolicLink -Target [network share folder path]

        network share folder path is generally defined as \\server\folder\

    Note the allure pdf report is also attached as build artifact

    browserLanguage

    • Use this parameter to define the language of Chrome browser (to differentiate it from the step definition aimed at changing the language of Sage X3).
    • If you don't define this parameter, the browser will be displayed by default in language en-US.
    • The language codes are the same as in Sage X3. (Arabic is not supported)

    logTechnicalDetails: If this parameter is set to true, technical information will be displayed in Jenkins log. Otherwise, they will be limited.

    JENKINS_NODE: This parameter defines on which Jenkins node you want to execute your ATP-RunAutomatedTests pipeline.

    • When the JENKINS_NODE parameter is left empty, your ATP-RunAutomatedTests pipeline is executed on any available nodes, based on the node strategy configured in Jenkins (Manage Jenkins > Manage nodes and clouds). If you didn’t configure any node, the pipeline is executed on the built-in node (master node for older Jenkins versions).

    • If the JENKINS_NODE parameter is defined, your ATP-RunAutomatedTests pipeline is executed on the chosen node.

    • The JENKINS_NODE parameter is based on the Jenkins node label.

    • To set up a label for a Jenkins node:

      1. Log in as an administrator.

      2. Go to the Jenkins home page.

      3. Select Manage Jenkins > Manage nodes and clouds.

      4. Select the settings icon for the specific node you want to set up.

      5. Define the label for the node. Spaces are not allowed.

      6. Save your changes.

      Note - informationThe built-in node in Jenkins has an internal label named built-in.

Executing your ATP-RunAutomatedTests pipeline

Now that you have configured your ATP-RunAutomatedTests pipeline you can execute the automated tests on your Sage X3 test environment that you have pushed on GitHub or on your Jenkins server.

  1. Check that you are connected as a Jenkins QualityTester user.
  2. Click ATP-RunAutomatedTests.
  3. Click Build with parameters.
  4. Leave the default parameter values or change if required. See Configuring your ATP-RunAutomatedTests pipeline.
  5. Select a value for the COPY_FEATURE_FROM, and associated COPY_FROM_FOLDER, parameters.

  1. Click Build.
  2. Refer to the Stage View block to view the progress of the build.

  3. Once the pipeline has executed, click the allure icon to access the build detail and open the generated Allure Report.

  4. When executing the Sage X3 Automated Test pipeline the following stages are executed

  • Stage Install/Update ATP:

    • This stage indicates the status of Sage X3 Automated Test Platform install or upgrade.

    • it is executed when the pipeline is executed for the first time, to install Sage X3 Automated Test Platform library.

    • Or if the UpdateATPX3 parameter is activated.

      • If a new version of Sage X3 Automated Platform is available, the upgrade is performed.

      • From version 3.2.2, you have to indicate in InstallPath parameter the location where the ATP Jenkins installer has been copied to install/update Sage X3 Automated Test Platform Library.

  • Stage Check User Stored values file:

    • This stage controls if the file path defined in the parameter userStoredValuesFile exists.

    • If the file path is incorrect, the pipeline execution is stopped.

  • Stage run prerequisite tests:

    • This stage indicates the status of the prerequisite tests execution.

    • It is executed if the parameter PREREQUISITE_SCRIPT_PATH is defined.

  • Stage tests execution:

    • This stage executes the automated tests.

      • It is named with the the path defined in the parameter FeatureFolders

      • There are as many stages as there are path defined in FeatureFolders parameter.

  • Stage generate report:

    • This stage indicates the status of the allure report generation.

  • Generate allure pdf:

    • This stage indicates the status of the processing to generate the allure report in pdf format.

    • It is executed when the allurePDFPrint parameter is activated.

Updating your ATP-RunAutomatedTests pipeline

Note - informationThis section is only applicable when a new version of the Jenkins pipeline template ATP-TemplateRunAutomatedTests is released.
Note - informationYou must complete this section if you have already installed and configured Jenkins with a version of Sage X3 Automated Test Platform older than version 2.4.0.
Note - dangerDo not update your ATP-RunAutomatedTests pipeline directly as the Jenkins parameters will be overwritten.

To avoid overwriting your Jenkins parameters you should update the Jenkins pipeline template ATP-TemplateRunAutomatedTests then report the changes to your ATP-RunAutomatedTests pipeline.

Updating the Jenkins pipeline template

The following steps update the Jenkins pipeline template ATP-TemplateRunAutomatedTests.

  1. Open your browser.
  2. Go to http:/[Jenkins server]:[port]/jnlpJars/jenkins-cli.jar, where [Jenkins server]:[port] is your Jenkins URL.
  3. Note - information A jenkins-cli.jar file is downloaded.
  4. Create a ATPJenkinsPipelineInstall folder in your Documents folder.
  5. Copy the Jenkins-cli.jar file to the ATPJenkinsPipelineInstall folder.
  6. Copy the ATP-TemplateRunAutomatedTests.xml file to the ATPJenkinsPipelineInstall folder.
  7. Note - information The ATP-TemplateRunAutomatedTests.xml file is in the atp-x.x.x-win zipped (compressed) file you downloaded to the 02-JenkinsPipeline folder.

  8. Open a new Windows PowerShell session in administrator mode.

  9. Change to the ATPJenkinsPipelineInstall directory.
  10. Enter the following command, replacing:
    1. [jenkins_account] with your Jenkins administrator account.
    2. [jenkins_password] with your Jenkins administrator password.
    3. [Jenkins_hostname]:[jenkins_port] with your Jenkins URL and port.

    type ATP-TemplateRunAutomatedTests.xml | java -jar jenkins-cli.jar -s http://[jenkins_account]:[jenkins_password]@[Jenkins_hostname]:[jenkins_port]/ update-job ATP-TemplateRunAutomatedTests

Note - successThe Jenkins pipeline template ATP-TemplateRunAutomatedTests has been updated.

Updating your ATP-RunAutomatedTests pipeline

The following steps update your ATP-RunAutomatedTests pipeline from the Jenkins pipeline template ATP-TemplateRunAutomatedTests.

  1. Go to the Jenkins home page.
  2. Select the ATP-TemplateRunAutomatedTests pipeline.
  3. Click Configure.
  4. Go to the Pipeline Script section.
  5. Copy the complete script.
  6. Close the page.
  7. Go to your ATP-RunAutomatedTests pipeline.
  8. Click Configure.
  9. Go to the pipeline Script section.
  10. Delete the existing script.
  11. Paste the script (that you copied in step 5).
  12. Create the new parameters delivered with the latest version of Sage X3 Automated Test Platform.

    To create these parameters, refer to their setup in the ATP-TemplateRunAutomatedTests Jenkins pipeline template or to the new parameters section.

  13. Click Apply, then Save.
  14. Note - successYour ATP-RunAutomatedTests pipeline will be updated with the new version when it is next executed.
  15. Approve pipeline to be executed by Jenkins:
    1. Go to the Jenkins home page
    2. Go to manage Jenkins > In-process Script approval
    3. Approve the script related to ATP-TemplateRunAutomatedTests pipeline, so the pipeline can be executed.
  16. Copy the Jenkins installer sagex3atp-jenkins-setup-M.m.p.jar provided in atp-M.m.p-win zip ( contained in 02-JenkinsPipelines folder) on your Jenkins server.

    • In ATPInstallerPath parameter: indicate the path where ATP Jenkins Installer has been copied: (e.g c:\ATP\sagex3atp-jenkins-setup-M.m.p.jar)

    • Note - warning

      If your ATP-RunAutomatedTestspipeline is executed on a Jenkins slave:

      • The Jenkins installer has to be copied on the Jenkins slave.

      • The path to indicate is the path where the installer has been copied on the Jenkins slave.

  17. Run your automated test pipeline with UpdateATPX3 parameter activated and ATPInstallerPath parameter defined to update version of Sage X3 Automated Test Platform.

New parameters

New parameters delivered with version Sage X3 Automated Test 2.3.0

loginUserRootName

  • type: string parameter

  • description: X3 ROOT Login user name

  • default value: adminname

loginUserRootPassword

  • type: string parameter

  • description: X3 ROOT Login password

  • default value: adminpassword

downloadFolder

  • type: string parameter

  • description: Folder where files will be downloaded while browsing

  • default value: C:\ATP\DOWNLOAD

New parameters delivered with version Sage X3 Automated Test 2.4.0

userStoredValuesFile

  • type: string parameter

  • description: User custom values file location

  • default value: cucumber-user-config/samples/samples-user-stored-values

New parameters delivered with version Sage X3 Automated Test 2.7.0

UpdateATPX3

  • type: boolean parameter

  • description: ATP / X3 Framework will be updated to the latest version.

  • default value: unticked

JENKINS_NODE

  • type: string parameter

  • description: Jenkins node(s) to run ATP tests. To run on the Built-In Node use label "built-in"

  • default value:

New parameters delivered with version Sage X3 Automated Test 3.0.0

timeout

  • type: string parameter

  • description: Selenium timeouts (implicit)

  • default value: 10000

timeoutLocks

  • type: string parameter

  • description : timeout maximum to lock test

  • default value: 240000

timeoutPrints

  • type: string parameter

  • description: timeout maximum to print report in X3.

  • default value: 120000

timeoutWaitfor

  • type: string parameter

  • description: WebdriverIO related timeouts

  • default value: 200000

timeoutCucumber

  • type: string parameter

  • description: Cucumber maximum timeout

  • default value: 300000

allurePDFPrint

  • type: boolean parameter

  • description: Print Allure report as a PDF

  • default value: unticked

allurePDFName

  • type: string parameter

  • description: PDF Report title and file name

  • trim the string: yes

  • default value: Allure-PDF-report

allurePDFPath

  • type : string parameter

  • description; Path to export report PDF to. Accepts Windows or Linux style relative or literal paths.

  • default value: allure-pdf

New parameters delivered with version Sage X3 Automated Test 3.2.2

browserLanguage

  • Type: string parameter

  • Default Value: en-US

  • Description: Language and locale to run the browser as. Leaving blank will default

To conceal the password of loginPassword and loginUserRootPassword parameters you have to delete existing parameters and recreate them with the following properties

loginPassword

  • Type: password parameter

  • Default Value: <the_required_password for the user defined in loginUserName parameter>

  • Description: X3 Login user name

loginUserRootPassword

  • Type: password parameter

  • Default Value: <required_password for the user defined in loginUserRootName parameter>

  • Description: X3 ROOT Login password

Then the password will be concealed

ATPInstallerPath

  • Type: string parameter

  • Name:

  • Default Value:

  • Description: Path to the ATP installer for Jenkins when updating

  • Trim the string: yes

New parameters delivered with version Sage X3 Automated Test 3.3.1

logTechnicalDetails

  • Type: boolean parameter

  • Default Value: false

  • Description: Show technical information in console log

ATPInstallerPath

  • Type: string parameter

  • Name:

  • Default Value:

  • Description: Path to the ATP installer for Jenkins when updating

  • Trim the string: yes

New parameters delivered with version Sage X3 Automated Test 4.0.0

ATPInstallerPath

  • Type: string parameter

  • Name:

  • Default Value:

  • Description: Path to the ATP installer for Jenkins when updating

  • Trim the string: yes