Professor M's School for Gifted Coders

Professor M's School for Gifted Coders is a module loadable package that can be installed in Sugar. The following sections explain more about the scenario and how to install the package and sample data.

Contents

About the scenario

Installation instructions

Setting up your development environment

Contribute to this project

Generating the Professor M module loadable packages locally

Continuous integration with Travis CI

Continuous integration with Jenkins

Automated tests

How to fix your Sugar instance without starting completely over

About the scenario

Professor M aka Professor Marum has created an exclusive not-for-profit school for gifted coders.

Learn more about the implemented Use Cases in the docs.

Want a quick summary? Watch the video below.

Installation instructions

Watch the video below for instructions on how to install the scenario. Text-based instructions follow.

Prerequisites

• Sugar 7.9.1.0 (or newer) installed with NO sample data. See Getting Started with Sugar Development for help.
  • Note: If you install Sugar using config_si.php, ensure that the disable_unknown_platforms property is set to false or is not in the file.
  • Note for Windows users: Make the path to your Sugar instance as short as possible to avoid errors of file paths being too long.
• Postman installed

Install the modules and customizations

We've created a custom package you can install. The package will create and customize the modules you'll need for the scenario. The following instructions will walk you throw how to install the package.

1. Download the appropriate zip file from the latest release. If you are installing in Sugar Cloud, you will need to select the production version of the release. If you are installing elsewhere, you can select the production release or the standard release. The standard release includes automated testing files while the production release does not.
2. Login to Sugar as an Administrator
3. Navigate to Administration > Module Loader
4. Upload sugarcrm-ProfessorM-standard.zip
5. Click Install for the ProfessorM package
6. Review and accept the license agreement
7. Click Commit
   • Hint for Windows users: If you receive a warning with the message "Full extraction path exceed MAXPATHLEN (260)...", try the following:
     1. Download sugarcrm-ProfessorM-windows.zip from the latest release.
     2. Install the zip as a module loadable package using the steps above.
     3. Download sugarcrm-ProfessorM-windows-manual-install.zip from the latest release.
     4. Unzip the file. Note that you'll find ProfMForWindowsReadme.txt and a set of directories inside of the zip. If no directories are inside the zip, then all file paths in the package/src directory have been deemed short enough to be included in a typical Windows installation and you will need to generate the zips yourself locally on your own machine (see Generating the Professor M module loadable packages locally for instructions on how to do so).
     5. Open ProfMForWindowsReadme.txt.
     6. Follow the instructions inside of the readme to manually copy the files from the zip to your Sugar instance. You may need to create directories in your Sugar directory if they do not already exist.
     7. Navigate to Administration > Repair > Quick Repair and Rebuild.
   • If the above installation still fails due to a MAXPATHLEN error, we recommend generating the zips yourself locally on your own machine. See Generating the Professor M module loadable packages locally for instructions on how to do so.

Customize the modules that are displayed

Sugar will display many modules by default that you will not be using while working on the tutorials. To make things simpler, we'll hide the modules that won't be used and rearrange the modules that are displayed.

1. Login to Sugar as an Administrator if you have not already done so
2. Go to Administration > Display Modules and Subpanels
3. Drag the following modules from the Displayed Modules box to the Hidden Modules box:
   • Calendar
   • Calls
   • Meetings
   • Tasks
   • Notes
   • Emails
   • Targets
   • Target Lists
   • Forecasts
   • Documents
   • Cases
   • Tags
4. Rearrange the items in the Displayed Modules box so they are in the following order from top to bottom:
   • Accounts
   • Leads
   • Contacts
   • Professors
   • Opportunities
   • Revenue Line Items
   • Quotes
   • Reports
   • Campaigns
   • Process Email Templates
   • Process Definitions
   • Process Business Rules
   • Processes
5. Click Save

Use the Sugar REST API to create the Professor M sample data

In order to create the Professor M sample data, you'll use Postman to run a collection of Sugar REST API calls. Each call in the collection has one or more simple tests associated with it to ensure the call was successful.

1. Save a copy of ProfessorM_PostmanCollection.json
2. In Postman, click Import
3. Click Choose Files and import ProfessorM_PostmanCollection.json
4. Click the gear icon in the upper right corner and select Manage Enviornments
5. Click Add
6. Input a name for your environment (for example, Professor M)
7. Add the following keys and values:
   • url: the url of your Sugar installation (for example, http://localhost:8888/profm)
   • rest_endpoint: /rest/v10
   • username: the username for an admin user in your Sugar installation
   • password: the password associated with the username above
8. Click Add
9. Close the Manage Environments dialog
10. Click Runner
11. Select the ProfessorM Sample Data collection
12. Ensure the environment you just created is selected
13. Click Run ProfessorM S...
14. Wait for the collection to finish running. All tests should pass. Hint: If you see many failures, you may have forgotten to install the Professor M module loadable package. See the instructions in previous section for how to do the install.

If you are using an Enterprise or Ultimate edition of Sugar, you can use the features that leverage Advanced Workflow. Save a copy of ProfessorM_PostmanCollection_AdvancedWorkflow.json and (https://raw.githubusercontent.com/sugarcrm/school/master/data/Application_Routing.bpm) to your local filesystem. Update the reference to Application_Routing.bpm in ProfessorM_PostmanCollection_AdvancedWorkflow.json to point to your local filesystem location for that file. Then follow the steps above to import the collection and run it.

Setting up your development environment

If you want to generate the Professor M module loadable packages yourself or make changes to the code in this repo, you will need to set up a development environment. You do NOT need to set up a development environment if you simply want to install the Professor M scenario as-is in your Sugar instance.

1. Checkout or download a copy of this repo.
2. Install PHP 7.
3. Install Composer. We use Composer to install the PHP dependencies for the project.
4. Execute the following command from your school/package directory in order to install the dependencies:

composer install

You may also want to set up your development environment so you can execute the unit tests. See Automated tests for more information.

Contribute to this project

Professor M's School is open source, and we would love for you to get involved! Below are some ways you can contribute to this project:

• Get notifications about this repo by clicking the Watch button at the top of this repo.
• Explore the code and use it as a resource as you develop your integrations and customizations.
• Create a new Issue if you have ideas for improvement, a feature request, or a bug report.
• Assign yourself an Issue, update the code, and create a pull request. See CONTRIBUTING.MD for more details.

ZenHub

We utilize ZenHub to organize our backlog and track our Issues. You can view our ZenHub board inside the GitHub web interface if you have a ZenHub browser extension installed. You can also view our ZenHub board at https://app.zenhub.com/workspace/o/sugarcrm/school/boards?repos=109023666.

When viewing our ZenHub board, you can view our prioritized backlog as well which stories are currently in progress, blocked, under review, and closed.

Generating the Professor M module loadable packages locally

The Professor M module loadable packages can be found on the Releases page of this GitHub repo. You may want to generate the module loadable packages yourself if you are a Windows user with a long Sugar directory path or if you want to make changes to the package.

1. Set up your development environment if you have not already done so.
2. In a shell, navigate to the package directory inside of your school directory.
3. For standard builds, execute ./pack.php -v versionNameOrNumber
4. For Windows builds where installing the standard build results in MAXPATHLEN errors, execute ./pack.php -v versionNameOrNumber -w lengthOfWindowsSugarDirectoryPath

Continuous integration with Travis CI

This repository is configured to work with Travis CI. Whenever a commit is pushed to the repository or a Pull Request is made, Travis CI will automatically kick off a build.

Viewing results in Travis CI

You can view the Travis CI build results at https://travis-ci.org/sugarcrm/school.

Viewing results in GitHub

You can view the latest build status at the top of this README ().
Clicking on the build status will open the detailed results in Travis CI.

You can also view build results in Pull Requests. Toward the bottom of each Pull Request, you can click "Show all checks" to see the Travis CI build results for that Pull Request.

You can then click Details to open the build results in Travis CI.

About the build

The build has four Environment Variables that have been configured in the project settings in Travis CI:

• SUGARCRM_USERNAME: The username for an account that has access to the SugarCRM Developer Builds Space and the Sugar Store
• SUGARCRM_PASSWORD: The password associated with the above account
• GITHUB_USERNAME: The username for a GitHub account that has access to https://github.com/sugarcrm/unit-tests
• GITHUB_PASSWORD: The password associated with the above account

The build is configured in .travis.yml. Currently, the build has three stages:

• Test PackageGenerator
• Run Tests
• Build & Post on GitHub

All of the jobs in each stage must pass before the jobs in the following stage will begin.

The Test PackageGenerator stage is run first and has two jobs:

• Execute the PHPUnit tests associated with the PackageGenerator (see PHPUnit tests for PackageGenerator for details).
• Execute the Jasmine tests associated with the PackageGenerator (see Jasmine tests for PackageGenerator for details). The PackageGenerator is responsible for creating the Professor M Module Loadable Package. This stage ensures that the PackageGenerator is functioning as we expect that it would. This stage does NOT test the Module Loadable Package.

The next stage to run is the Run Tests stage. Each job in this stage deploys Sugar, installs the Professor M Module Loadable Package, runs the setup for the PHPUnit tests that Sugar provides, runs the PHPUnit tests written specifically for our Professor M Module Loadable Package, and runs the Postman tests. Each job in this stage is run against a different combination of Sugar versions and editions. See PHPUnit tests for the Professor M Module Loadable Package for details.

The final stage to run is the Build & Post on GitHub stage. Note that this stage is only run when the branch is Master. This stage executes the pack.php script to generate the Professor M Module Loadable Packages as zips. The zips will be automatically posted to GitHub: https://github.com/sugarcrm/school/releases.

If you want the Build & Post on GitHub stage to be kicked off for a branch other than master, you should do both of the following in .travis.yml.

• Remove the "if: branch = master" in the stages section
• Add the branch as an option in the deploy section. For example:

    deploy:
      provider: releases
      file: releases/sugarcrm-ProfessorM-latest.zip
      api_key:
          secure: mykey
      skip_cleanup: true
      on:
        branch: mybranchname

Continuous integration with Jenkins

This repository can be configured for continuous integration with Jenkins. Jenkins can be configured so that whenever a commit is pushed to the repository or at certain time intervals, Jenkins will automatically kick off a build.

Installing Jenkins

Before beginning, you'll need to set up your own installation of Jenkins. Check out the Jenkins Installation Guide for more details.

To help you get started, we have provided PrepareJenkinsDockerContainer.sh that you can run to start Jenkins inside of a Docker container. The machine or container where Jenkins is running will need to have Docker Compose and Perl installed. PrepareJenkinsDockerContainer.sh will take care of installing both for you. If you use PrepareJenkinsDockerContainer.sh, you should be able to access Jenkins at http://localhost:8080.

We recommend installing the Jenkins suggested plugins. You will also need to install the EnvInject Plugin.

Storing Credentials in Jenkins

The build you will create in Jenkins needs access to credentials and configurations. We will store these using Jenkins Credentials.

The instructions below will walk you through how to create the necessary credentials and configurations. For more information on how to store credentials in Jenkins, see Credentials Binding Plugin.

1. On the Jenkins dashboard, click Credentials. (If you do not see the Credentials option, you may need to install the Credentials Binding Plugin.)
2. Create new global credentials for the GitHub account that has access to the SugarCRM Unit Tests repo.
   1. Kind: Username with password
   2. Scope: Global
   3. Username: your GitHub username
   4. Password: your GitHub password
   5. ID: GITHUB_SUGARCRM_UNIT_TESTS
   6. Description: GitHub account that has access to https://github.com/sugarcrm/unit-tests
3. Create new global credentials for the account that has access to the SugarCRM Developer Builds Space and the Sugar Store.
   1. Kind: Username with password
   2. Scope: Global
   3. Username: your SugarCRM username
   4. Password: your SugarCRM password
   5. ID: SUGARCRM_ACCOUNT
   6. Description: SugarCRM Account
4. Create a new global secret for the Sugar license key.
   1. Kind: Secret text
   2. Scope: Global
   3. Secret: Your Sugar license key. This secret is used by InstallSugarAndProfM.sh.
   4. ID: SUGAR_LICENSE_KEY
   5. Description: The Sugar license key

Creating a Jenkins project

Now you're ready to create a new project in Jenkins that will build the school project.

1. On the Jenkins dashboard, click New Item.

2. Name your new item something like ProfessorM.

3. Select Freestyle project and click OK. The item configuration page will display.

4. In the Source Code Management section, select Git.

5. Input your Repository URL (for example, https://github.com/sugarcrm/school) and select the GitHub credentials you created in the previous section.

6. Configure the Build Triggers section as you'd like. If you do not want to configure this now, you can skip this step and manually trigger the builds instead.

7. In the Build Environment section, select the Delete workspace before build starts option and the Use secret text(s) or file(s) option.

8. In the Bindings section, select Add > Username and password (separated). Then input the following:

   1. Username Variable: GITHUB_USERNAME
   2. Password Variable: GITHUB_PASSWORD
   3. Credentials: Specific credentials
   4. Select the GITHUB_SUGARCRM_UNIT_TESTS credentials.

9. In the Bindings section, select Add > Username and password (separated). Then input the following:

   1. Username Variable: SUGARCRM_USERNAME
   2. Password Variable: SUGARCRM_PASSWORD
   3. Credentials: Specific credentials
   4. Select the SUGARCRM_ACCOUNT credentials.

10. In the Bindings section, select Add > Secret text. Then input the following:

    1. Variable: SUGAR_LICENSE_KEY
    2. Credentials: Specific credentials
    3. Select the SUGAR_LICENSE_KEY secret text.

11. In the Bindings section, select the Inject environment variables to the build process checkbox. If you do not see this checkbox, you may need to install the EnvInject Plugin. Then...

    1. In the Properties Content input box, add a line for the WORKSPACE_PATH variable. This path represents the path to the workspace for your Jenkins job on the host machine. For example, if your Jenkins home directory is /Users/lschaefer/jenkins and your Jenkins project is named ProfessorM, you would input the following: WORKSPACE_PATH=/Users/lschaefer/jenkins/workspace/ProfessorM
    2. In the Properties Content input box, add a line for the PATH_TO_SUGAR_DOCKER_ON_HOST variable. This variable represents the path to Sugar Docker on the host machine. If you want to use the default location, input the following: PATH_TO_SUGAR_DOCKER_ON_HOST=$WORKSPACE_PATH/scripts/workspace/sugardocker If you want to customize where Sugar Docker is stored, you can update this variable to reflect that.

12. In the Build section, click Add build step and select Execute shell.

13. In the Command box that appears, input the following:

    # The Sugar version you want to test
    SUGAR_VERSION="7.11"
    
    # The Sugar Edition you want to test. Options: Pro, Ent, and Ult
    SUGAR_EDITION="Ent"
    
    # Path to where the Sugar Docker directory should be stored. If you do not have a preference, leave this as is.
    SUGAR_DOCKER_DIRECTORY="workspace/sugardocker"
    
    # This variable is completely optional.  If you want to store the Sugar source zips on your local machine instead
    # of downloading them from the SugarCRM Developer Builds space or Sugar Store, input the path to where the Sugar 
    # source zips are stored. For example: /var/sugardocker/data/app/sugar_source_zips. Note that your Sugar source zips 
    # MUST follow this naming convention: Sugar$sugarEdition-$sugarVersion.zip (for example: SugarEnt-7.11.zip).
    # SUGAR_SOURCE_ZIPS_DIRECTORY=""
     
    cd scripts
     
    bash -ex RunPackUnitTestsAndBuildProfMPackage.sh $SUGAR_WORKSPACE_PATH
     
    bash SetupEnvAndRunTests.sh $SUGARCRM_USERNAME $SUGARCRM_PASSWORD $SUGAR_VERSION $SUGAR_EDITION $GITHUB_USERNAME $GITHUB_PASSWORD $SUGAR_DOCKER_DIRECTORY $SUGAR_SOURCE_ZIPS_DIRECTORY
    

    Be sure to update the variables appropriately.

14. In the Post-build Actions section, click Add post-build action and select Archive the artifacts.

15. In the Files to archive box that appears, input the following: package/releases/*.zip

16. Click Save.

Running a build and viewing the results

Once you have your Jenkins project created, it's time to see if it works!

Navigate to your ProfessorM project in Jenkins. Trigger your build manually by clicking Build Now.

View the Build History panel to quickly browse the build results. If you see a blue dot, you know all of the tests passed!

Click on a build to view more details. If the build passed, the Professor M module loadable packages will be stored as build artifacts.

To see more details on a build, click Console Output. If any step in the process fails (for example, a Jasmine test fails), the remaining steps will not be run. If everything succeeds, you'll be able to find the Jasmine test results for PackageGenerator, the PHPUnit test results for PackageGenerator, the PHPUnit test results for Sugar, the PHPUnit tests for the Professor M Module Loadable Package, and the results of the Professor M module loadable packages being generated, copied, and archived.

Jasmine results for PackageGenerator:

PHPUnit results for PackageGenerator:

PHPUnit results for the Professor M Module Loadable Package:

Postman test results:

Professor M package results:

Tip: If you see errors in the Console Output about git not being found, you may need to update your Jenkins configuration. On the Jenkins dashboard, click Manage Jenkins. Click Conifgure System. In the Global Properties section, enable the Tool Locations checkbox. In the Name box, select (Git) Default. In the Home box, input the path to the Git installation (for example, /usr/bin/git). Click Save.

Tip for those running Jenkins in Docker: If you see errors in the Console Output similar to 'Fatal error: Unable to find local grunt', you may need to update your Jenkins job. The likely cause is that your $SUGAR_WORKSPACE_PATH is not pointing to the path of the workspace that is storing the school repo's files that are being pulled out of GitHub. You can diagnose if this is the issue by adding docker exec my-yarn pwd and docker exec my-yarn ls around line 18 of RunPackUnitTestsAndBuildProfMPackage.sh to see what is in the workspace directory after the docker run command has mounted the volume. If you do not see files from the school repo in the workspace, you need to update $SUGAR_WORKSPACE_PATH.

About the build

The build calls two scripts

1. RunPackUnitTestsAndBuildProfMPackage.sh
2. SetupEnvAndRunTests.sh

RunPackUnitTestsAndBuildProfMPackage.sh has three key parts:

1. Run the Jasmine tests that test PackageGenerator
2. Run the PHPUnit tests that test PackageGenerator
3. Build the Professor M Module Loadable Packages using the PackageGenerator

This script relies on Docker images stored on Docker Hub in order to implement the three parts listed above. The sugarcrmdev/school Docker Hub repository stores two images:

• The yarn image has all of the dependencies managed by Yarn installed in it. The shell script uses this image to run the Jasmine tests.
• The composer image has all of the dependencies managed by Composer installed in it. The shell script uses this image to run the PHPUnit tests as well as to generate the Professor M module loadable packages.

This script does NOT test the Module Loadable Package.

The next step is to run SetupEnvAndRunTests.sh. This script deploys Sugar, installs the Professor M Module Loadable Package, runs the setup for the PHPUnit tests that Sugar provides, runs the PHPUnit tests written specifically for our Professor M Module Loadable Package, and runs the Postman tests.

Note: if any step in the process fails (for example, a Jasmine test fails), the remaining steps will not be run.

Automated tests

This repository contains various automated tests. We'll discuss each category of tests below.

Testing PackageGenerator.php

This repository contains automated PHPUnit and Jasmine tests specifically for testing PackageGenerator. Since PackageGenerator does not require the Sugar code base in order to run, these tests can be executed separate from the Sugar code base.

These tests can be executed manually or as part of a continuous integration build.

PHPUnit tests for PackageGenerator

PHPUnit is a testing framework for PHP. The PHPUnit test files are located in /tests/phpunit. The /tests/phpunit directory can contain multiple test files, and each test file can contain multiple tests.

Manual execution

To manually execute the tests, you will need to use Composer to install PHPUnit and other PHP dependencies. If you have not installed Composer before, visit the Composer Getting Started Guide.

Execute the following command from your school/package directory in order to install the test dependencies:

composer install

If you need to update the namespaces, manually update composer.json and then run the following command from your school/package directory:

./composer.phar update

The PHPUnit tests can be executed by running the following command from your school/tests/phpunit directory on macOS:

../../package/vendor/bin/phpunit

or on Windows:

..\..\package\vendor\bin\phpunit

Automatic execution in Travis CI

The PHPUnit tests are automatically run as part of the Test PackageGenerator stage of the Travis CI build. Travis CI's default build script for PHP is PHPUnit, so we don't have to include anything special in .travis.yml in order for the tests to run. However, we have added composer install to .travis.yml in order for the dependencies to be installed on the build machine. Travis CI looks in phpunit.xml for the PHPUnit config. Our config indicates that the PHPUnit tests are stored in tests/phpunit.

Interpreting the results

To see the results of the tests that are run as part of the Travis CI build, open the build in Travis CI. If the build passed, you know all of the tests passed.

To see the detailed test results, click the PHP build job to expand it:

You can scroll through the job log to see the results of the PHPUnit tests.

If the build failed, a variety of things could have caused the failure including a failing PHPUnit test.

If a PHPUnit test fails, you'll see something like the following in the job log.

Automatic execution in Jenkins

The PHPUnit tests are automatically run as part of the Jenkins build when RunPackUnitTestsAndBuildProfMPackage.sh is executed.

Interpreting the results

To see the results of the tests that are run as part of the Jenkins build, open the build in Jenkins. If the build passed, you know all of the tests passed.

To see the detailed test results, open the build and click Console Output. You can scroll through the job log to see the results of the PHPUnit tests. Note: you may need to open the Full Log to find the results.

If the build failed, a variety of things could have caused the failure including a failing PHPUnit test.

If a PHPUnit test fails, you'll see something like the following in the job log.

Jasmine tests for PackageGenerator

Jasmine is a testing framework for JavaScript. We have included a very simple Jasmine test in this repository as an example.

The tests are located in /tests/jasmine/specs. Currently, there is one test inside of the DummySpec.js test file. The /tests/jasmine/specs directory can contain multiple test files, and each test file can contain multiple tests.

Manual execution

To manually execute the tests, you will need to install a few different things on your machine before you can run the tests.

Setup

Install Yarn which is an NPM compatible package manager. See Yarn Installation Guide for more details on how to install Yarn.

Next navigate to your school directory and then execute the following commands.

Navigate to the tests/jasmine directory.

cd tests/jasmine

Install the JavaScript dependencies using Yarn. These dependencies include Grunt, Jasmine, and Phantomjs.

yarn install

Install the Grunt command line interface globally. See Grunt's Getting Started Guide for more details on installing and using Grunt.

yarn global add grunt-cli

Execution

Inside of your tests/jasmine directory, execute the following command to run the Jasmine tests:

grunt test-js

Automatic execution in Travis CI

The Jasmine tests are automatically run as part of the Travis CI build process. In .travis.yml, the Test PackageGenerator stage kicks off the "test-js" task.

Interpreting the results

To see the results of the tests that are run as part of the Travis CI build, open the build in Travis CI. If the build passed, you know all of the tests passed.

To see the detailed test results, click the Node.js build job to expand it:

You can scroll through the job log to see the results of the Jasmine tests.

If the build failed, a variety of things could have caused the failure including a failing Jasmine test.

If a Jasmine test fails, you'll see something like the following in the job log.

Automatic execution in Jenkins

The Jasmine tests are automatically run as part of the Jenkins build when RunPackUnitTestsAndBuildProfMPackage.sh is executed.

Interpreting the results

To see the results of the tests that are run as part of the Jenkins build, open the build in Jenkins. If the build passed, you know all of the tests passed.

To see the detailed test results, open the build and click Console Output. You can scroll through the job log to see the results of the Jasmine tests. Note: you may need to open the Full Log to find the results.

If the build failed, a variety of things could have caused the failure including a failing Jasmine test.

If a Jasmine test fails, you'll see something like the following in the job log.

Testing Sugar and the Professor M Module Loadable Package

Many customizations in the Professor M Module Loadable Package require a copy of the Sugar code in order to compile and/or run. Therefore, we will only test the Professor M Module Loadable Package after it has been installed in Sugar.

In this section, we'll discuss how to run the automated tests for the Professor M Module Loadable Package. Since the setup for running the Sugar provided automated tests is so similar, we will discuss how to do that here as well.

Currently, we have PHPUnit tests and Postman tests.

PHPUnit tests for the Professor M Module Loadable Package

PHPUnit is a testing framework for PHP. The PHPUnit test files are located in package/src/custom/tests/unit-php/School.

Manual execution

There are two primary ways to manually execute the PHPUnit tests. We'll explore both below.

Manual execution using Docker

The easiest way to run the PHPUnit tests is to run the same scripts that the automated tests run.

First, you will need to install Docker, Docker Compose, and Perl. If the script will be downloading a copy of Sugar from the Sugar Store or the Sugar Developer Builds Community (instead of using a copy of Sugar stored on your machine), you will also need a package installed that can execute the sha1sum command. On a Mac, you can install md5sha1sum by executing brew install md5sha1sum in a shell.

Then execute SetupEnvAndRunTests.sh. Note that the Sugar provided unit tests are NOT run as part of SetupEnvAndRunTests.sh. If you want to add them, add the following line after the call to SetupSugarPHPUnitTests.sh:

./RunSugarPHPUnitTests.sh $sugarDirectory || exit 1

Manual execution in an installed version of Sugar

If you are actively developing the Professor M Module Loadable Package, you will most likely want to run the unit tests as you are working and making updates to the code.

In order to manually execute the tests, you will need a running copy of Sugar that has been installed with no sample data. See Getting Started with Sugar Development for instructions on setting up a development environment.

You will also need to get a copy of the Sugar provided unit tests and put them in your Sugar source code directory. See the SugarCRM unit tests GitHub repo for more information.

Prepare to run the Sugar provided PHPUnit tests and the Professor M PHPUnit tests by executing the following commands:

$ cd /path/to/sugar_source_dir
$ composer install
$ cd tests/unit-php
$ chmod +x ../../vendor/bin/phpunit

Run the Sugar provided unit tests by executing the following command from the tests/unit-php directory:

$ ../../vendor/bin/phpunit

Install the standard version of the Professor M Module Loadable Package using Module Loader if you have not already done so. The code for Professor M and the associated tests will be installed in to the Sugar source directory.

Run the Professor M PHPUnit tests by executing the following command from the tests/unit-php directory:

$ ../../vendor/bin/phpunit --testsuite custom

Automatic execution in Travis CI

The PHPUnit tests that test the Professor M Module Loadable Package are automatically run as part of the Run Tests stage of the Travis CI build.

Each job in this stage is basically the same with the exception of the environment variables. Each job calls SetupEnvAndRunTests.sh, which executes the Professor M PHPUnit tests.

Note that the Sugar provided unit tests are NOT run as part of SetupEnvAndRunTests.sh. If you want to add them, add the following line after the call to SetupSugarPHPUnitTests.sh:

./RunSugarPHPUnitTests.sh $sugarDirectory || exit 1

Interpreting the results

To see the results of the tests that are run as part of the Travis CI build, open the build in Travis CI. If the build passed, you know all of the tests passed.

To see the detailed test results, click a job in the Run Tests stage:

You can scroll through the job log to see the results of the PHPUnit tests.

If the build failed, a variety of things could have caused the failure including a failing PHPUnit test.

If a PHPUnit test fails, you'll see something like the following in the job log.

Automatic execution in Jenkins

The PHPUnit tests that test the Professor M Module Loadable Package are automatically run as part of the Jenkins build when SetupEnvAndRunTests.sh is run.

Note that the Sugar provided unit tests are NOT run as part of SetupEnvAndRunTests.sh. If you want to add them, add the following line after the call to SetupSugarPHPUnitTests.sh:

 ```
 ./RunSugarPHPUnitTests.sh $sugarDirectory || exit 1
 ```

Interpreting the results

To see the results of the tests that are run as part of the Jenkins build, open the build in Jenkins. If the build passed, you know all of the tests passed.

To see the detailed test results, open the build and click Console Output. You can scroll through the job log to see the results of the PHPUnit tests.

If the build failed, a variety of things could have caused the failure including a failing PHPUnit test.

If a PHPUnit test fails, you'll see something like the following in the job log.

Postman tests for the Professor M Module Loadable Package

Postman is an API development environment. We use Postman Collections to insert our sample data into Sugar via the REST API. Each API call in the collections has one or more associated tests to ensure the calls were successful.

The Postman Collections can be run via the Postman application as described above or the command line using Newman.

Manual execution using the command line interface

You can execute the tests against any running instance of Sugar. Note that the Postman tests will NOT be installed as part of the Professor M module loadable package. The tests will only be available in your school repo.

The first step is to configure the Postman Environment for your particular instance of Sugar. Open ProfessorM_PostmanEnvironment and update the url, username, password, and rest_endpoint to reflect your instance.

Then you can choose to install Newman to execute the tests or use a Docker image to execute the tests.

Using Newman

Install Node.js if you haven't already.

Install Newman by executing the following:

npm install -g newman

Navigate to the school/data directory in your shell. Execute the tests by running the following:

newman run ProfessorM_PostmanCollection.json -e ProfessorM_PostmanEnvironment.json

You can execute the tests that leverage Advanced Workflow (only available in Enterprise and Ultimate editions of Sugar) by running the following:

newman run ProfessorM_PostmanCollection_AdvancedWorkflow.json -e ProfessorM_PostmanEnvironment.json

Using Docker

Install Docker if you haven't already.

Pull the Newman Docker container that we will use to run the tests by executing the following:

docker pull postman/newman_ubuntu1404

Execute the tests by running the following:

docker run -v pathToTheDataDirectoryInYourSchoolRepo:/etc/newman -t postman/newman_ubuntu1404 run "ProfessorM_PostmanCollection.json" --environment="ProfessorM_PostmanEnvironment.json"

Be sure to replace pathToTheDataDirectoryInYourSchoolRepo with the path to the data directory in your school repo.

You can execute the tests that leverage Advanced Workflow (only available in Enterprise and Ultimate editions of Sugar) by running the following:

docker run -v pathToTheDataDirectoryInYourSchoolRepo:/etc/newman -t postman/newman_ubuntu1404 run "ProfessorM_PostmanCollection_AdvancedWorkflow.json" --environment="ProfessorM_PostmanEnvironment.json"

Hint: If your instance of Sugar is running inside a Docker container, you may need to add the --net="host" option:

docker run -v pathToTheDataDirectoryInYourSchoolRepo:/etc/newman --net="host" -t postman/newman_ubuntu1404 run "ProfessorM_PostmanCollection.json" --environment="ProfessorM_PostmanEnvironment.json"

Automatic Execution in Travis CI

The Postman tests are automatically run as part of the Run Tests stage of the Travis CI build.

Each job in this stage is basically the same with the exception of the environment variables. Each job calls SetupEnvAndRunTests.sh, which executes the Postman tests.

Interpreting the results

To see the results of the tests that are run as part of the Travis CI build, open the build in Travis CI. If the build passed, you know all of the tests passed.

To see the detailed test results, click a job in the Run Tests stage:

You can scroll through the job log to see the results of the Postman tests.

If the build failed, a variety of things could have caused the failure including a failing Postman test.

If a Postman test fails, you'll see something like the following in the job log.

Automatic execution in Jenkins

The Postman tests are automatically run as part of the Jenkins build when SetupEnvAndRunTests.sh is run.

Interpreting the results

To see the results of the tests that are run as part of the Jenkins build, open the build in Jenkins. If the build passed, you know all of the tests passed.

To see the detailed test results, open the build and click Console Output. You can scroll through the job log to see the results of the Postman tests.

If the build failed, a variety of things could have caused the failure including a failing Postman test.

If a Postman test fails, you'll see something like the following in the job log.

How to fix your Sugar instance without starting completely over

As you customize this instance, you may do something like accidentally write broken code that seems to break your Sugar instance. Try running Quick Repair and Rebuild:

1. Log in as an administrator.
2. Click your profile picture in the upper-right corner and select Administration.
3. In the System section, click Repair.
4. Click Quick Repair and Rebuild.

If you become unable to login to your Sugar instance or running Quick Repair does not work, try the following:

1. Remove the custom code that is causing problems.
2. Delete the contents of the cache directory.
3. Use a program like MySQL Workbench to truncate the metadata_cache table.
4. Access your Sugar instance in a browser. If you still receive an error, reload the page.

If the above steps do not fix your problem, you may need to start over. Delete your Sugar root directory and follow the steps in the Installation Instructions above.