6.7. Test Your E-Commerce Application

To test new applications that you develop for the E-Commerce service, you create and run tests for the Open edX platform first, and then you run a set of tests that are specific to E-Commerce.

For more information about tests for the Open edX platform, see Testing Open edX Features in the Open edX Developer’s Guide.

6.7.1. Tests for E-Commerce

When you develop E-Commerce applications, you must run a pre-packaged set of unit tests, Python tests, and E-Commerce acceptance tests.

6.7.1.1. Run E-Commerce Unit Tests

The E-Commerce unit tests include migrations, the unit test suite, and quality checks. You can run the full unit test, or save time for a local test by disabling the migrations. (You can also run the quality checks independent of the unit test suite.)

  • To run the full unit test, including migrations and quality checks, use the following command.

    $ make validate
    

    Note

    If numerous unit tests fail with an OfflineGenerationError message, run the following command, then try to run unit tests again.

    $ DJANGO_SETTINGS_MODULE=ecommerce.settings.test make static
    
  • To run unit tests with quality checks but without migrations, run the following command.

    $ DISABLE_MIGRATIONS=1 make validate
    

    Note

    We recommend that you only run tests without migrations when you run the tests locally.

  • To validate code quality independently, run the following command.

    $ make quality
    

6.7.1.1.1. Python Unit Tests

When you create E-Commerce tests, use the TestCase class in ecommerce/tests/testcases.py to ensure every test has Site and Partner objects configured. This will help you test any code that relies on these models, which are used for multi-tenancy.

  • To run all Python unit tests and quality checks, run the following command.

    $ make validate_python
    
  • To run all Python unit tests and quality checks in parallel, run the following command.

    $ make fast_validate_python
    
  • To run the Python unit tests in a specific file, such as ecommerce/courses/tests/test_utils.py, run the following command and substitute the desired file path.

    $ DISABLE_ACCEPTANCE_TESTS=True ./manage.py test
    ecommerce.courses.tests.test_utils --settings=ecommerce.settings.test
    --with-ignore-docstrings --logging-level=DEBUG
    

    Setting the DISABLE_MIGRATIONS variable significantly decreases the time needed to run tests by creating the test database directly from Django model definitions as opposed to applying the defined migrations.

    $ DISABLE_MIGRATIONS=1 DISABLE_ACCEPTANCE_TESTS=True ./manage.py test
    ecommerce.courses.tests.test_utils --settings=ecommerce.settings.test
    --with-ignore-docstrings --logging-level=DEBUG
    

6.7.1.1.2. JavaScript Unit Tests

The E-Commerce project uses Jasmine for JavaScript unit testing. To create these tests, place your tests in the ecommerce/static/js/test/specs directory, and add a _spec suffix. For example, your test name may be ecommerce/static/js/test/specs/course_list_view_spec.js.

All JavaScript code must adhere to standards outlined in the edX JavaScript Style Guide. These standards are enforced using ESLint.

  • To run all JavaScript unit tests and linting checks, run the following command.

    $ make validate_js
    

6.7.1.2. Run E-Commerce Acceptance Tests

To run specific acceptance tests for the E-Commerce service, you must complete the following procedures.

6.7.1.2.1. Configure the LMS

To configure the LMS, follow these steps.

  1. Ensure devstack Vagrant virtual machine (“VM”) is up and running.

    vagrant up
    
  2. Sign in to the VM.

    vagrant ssh
    
  3. Become the edxapp user.

    sudo su edxapp
    
  4. Verify that the following settings in /edx/app/edxapp/lms.env.json are correct.

    "ECOMMERCE_API_URL": "http://localhost:8002/api/v2/"
    "ECOMMERCE_PUBLIC_URL_ROOT": "http://localhost:8002"
    "JWT_ISSUER": "http://127.0.0.1:8000/oauth2" // Must match the E-Commerce JWT_ISSUER setting
    "OAUTH_ENFORCE_SECURE": false
    "OAUTH_OIDC_ISSUER": "http://127.0.0.1:8000/oauth2"
    
  5. Verify that the following settings in /edx/app/edxapp/lms.auth.json are correct.

    "ECOMMERCE_API_SIGNING_KEY": "insecure-secret-key" // Must match the E-Commerce JWT_SECRET_KEY setting
    "EDX_API_KEY": "PUT_YOUR_API_KEY_HERE" // Must match the E-Commerce EDX_API_KEY setting
    
  6. Verify that an LMS account with staff and superuser permissions exists.

    By default, most devstack and fullstack LMS instances include a user account that has staff permissions. This account has the username staff, the email address staff@example.com, and the password edx. Run the following commands to grant the account superuser permissions.

    cd ~/edx-platform
    ./manage.py lms set_superuser staff --settings=devstack
    
  7. Start the LMS.

  8. Navigate to the OAuth2 Clients section of the Django administration console (e.g. http://localhost:8000/admin/oauth2/client/). Sign in using the superuser account you created earlier.

    Verify that an OAuth2 client with the following attributes exists. If one does not already exist, create a new OAuth 2 client.

    The client ID and secret must match the values of the E-Commerce SOCIAL_AUTH_EDX_OIDC_KEY and SOCIAL_AUTH_EDX_OIDC_SECRET settings, respectively.

    Name: ecommerce
    URL: http://localhost:8002/
    Redirect URI: http://localhost:8002/complete/edx-oidc/
    Client ID: 'ecommerce-key'
    Client Secret: 'ecommerce-secret'
    Client Type: Confidential (Web applications)
    Logout url: http://localhost:8002/logout/
    
  9. Navigate to the Edx_Oauth2_Provider Trusted clients section of the Django administration console (http://localhost:8000/admin/edx_oauth2_provider/trustedclient/).

    Verify that the OAuth2 client referred to above is designated as a trusted client (look for the Redirect URI). If this isn’t already the case, add the client created above as a new trusted client.

  10. In the Django administration panel, create a new access token for the superuser account. Set the client to the OAuth2 client referred to above. Make note of this token; it is required to run the acceptance tests.

  11. Make sure that the LMS instance that you will use for testing has at least two courses that learners can enroll in. By default, most LMS instances include the edX demonstration course. Use Studio to create a second course.

6.7.1.2.2. Configure E-Commerce

You use the E-Commerce Course Administration Tool (“ECAT”) to finish configuring the two courses in your LMS instance.

  1. Become the ecommerce user.

    sudo su ecommerce
    
  2. Verify that the following keys in /edx/etc/ecommerce.yml match your settings in /edx/app/edxapp/lms.env.json and /edx/app/edxapp/lms.auth.json.

    • One of the JWT_AUTH:JWT_ISSUERS entries should match /edx/app/edxapp/lms.env.json:JWT_ISSUER. The default value is http://127.0.0.1:8000/oauth2.
    • JWT_AUTH:JWT_SECRET_KEY should match /edx/app/edxapp/lms.auth.json:ECOMMERCE_API_SIGNING_KEY. The default value is lms-secret.
    • EDX_API_KEY should match /edx/app/edxapp/lms.auth.json:EDX_API_KEY. The default value is PUT_YOUR_API_KEY_HERE.
  3. Set up the E-Commerce environment.

    cd /edx/app/ecommerce/ecommerce
    source ../ecommerce_env
    source ../venvs/ecommerce/bin/activate
    make requirements
    make static
    make migrate
    
  4. Create a new site linking to the LMS.

    ./manage.py create_or_update_site \
      --site-id=1 \
      --site-domain=localhost:8002 \
      --partner-code=edX \
      --partner-name='Open edX' \
      --lms-url-root=http://localhost:8000 \
      --theme-scss-path=sass/themes/edx.scss \
      --payment-processors=cybersource,paypal \
      --client-id=ecommerce-key \
      --client-secret=ecommerce-secret \
      --from-email staff@example.com
    
  5. Start the E-Commerce Django development server.

    ./manage.py runserver 0.0.0.0:8002
    
  6. Get the course key from the LMS by navigating to a course and examining its URL. The course key should look something like course-v1:edX+DemoX+Demo_Course.

  7. Navigate to the E-Commerce Courses page (http://localhost:8002/courses/) to add the two test courses that are on your LMS instance to E-Commerce. Configure one course as a “Free (Audit)” course, and the second as a “Verified” course.

  8. To configure the “Verified” course, click Add New Course. Leave the default values in all fields, with the exception of the following fields.

    Course ID: The course key from the LMS
    Course Name: Use any name
    Course Type: Verified
    Include Honor Seat: No
    
  9. Navigate to the learner dashboard (e.g. http://localhost:8000/dashboard) and confirm that the course you added in E-Commerce now has a green “Upgrade to Verified” badge, which you can select.

  10. In the ECAT, add the second course on your LMS instance to E-Commerce. Specify its course type as Free (Audit).

  11. To test integration with external payment processors, update the contents of the PAYMENT_PROCESSOR_CONFIG dictionary found in the settings with valid credentials. To override the default values for development, create a private settings module, private.py, and set PAYMENT_PROCESSOR_CONFIG inside the module.

    Note

    If you created a private.py file to create settings overrides when you set up your virtual environment, you can use that same private.py file.

6.7.1.2.3. Configure Acceptance Tests

You configure acceptance tests by using the settings in the e2e/config.py file. You can use the default values for most settings in this file. However, for the following settings, you must specify values using environment variables.

Variable Description
ACCESS_TOKEN The OAuth2 access token used to authenticate requests.
ECOMMERCE_URL_ROOT The URL root for the E-Commerce service.
LMS_URL_ROOT The URL root for the LMS.
LMS_USERNAME A username for any current LMS user, to use during testing.
LMS_EMAIL The email address used to sign in to the LMS.
LMS_PASSWORD The password used to sign in to the LMS.

If you test PayPal integration, you must also specify values for the following settings by using environment variables.

Variable Description
PAYPAL_EMAIL The email address used to sign in to PayPal during payment.
PAYPAL_PASSWORD The password used to sign in to PayPal during payment.

6.7.1.2.4. Run Acceptance Tests

Run all acceptance tests by executing make e2e.

To run a specific test, execute the following command.

$ nosetests -v <path/to/the/test/module>

The acceptance tests rely on the environment variables that you have configured. For example, when you run the acceptance tests against local instances of E-Commerce and the LMS, you might run the following command, replacing values between angle brackets (<>) with your own values.

$ ECOMMERCE_URL_ROOT="http://localhost:8002" LMS_URL_ROOT="http://127.0.0.1:8000" LMS_USERNAME="<username>" LMS_EMAIL="<email address>" LMS_PASSWORD="<password>" ACCESS_TOKEN="<access token>" LMS_HTTPS="False" LMS_AUTO_AUTH="True" PAYPAL_EMAIL="<email address>" PAYPAL_PASSWORD="<password>" ENABLE_CYBERSOURCE_TESTS="False" VERIFIED_COURSE_ID="<course ID>" make e2e

When you run the acceptance tests against a production-like staging environment, you might run the following command.

$ ECOMMERCE_URL_ROOT="https://ecommerce.stage.edx.org" LMS_URL_ROOT="https://courses.stage.edx.org" LMS_USERNAME="<username>" LMS_EMAIL="<email address>" LMS_PASSWORD="<password>" ACCESS_TOKEN="<access token>" LMS_HTTPS="True" LMS_AUTO_AUTH="False" PAYPAL_EMAIL="<email address>" PAYPAL_PASSWORD="<password>" BASIC_AUTH_USERNAME="<username>" BASIC_AUTH_PASSWORD="<password>" HONOR_COURSE_ID="<course ID>" VERIFIED_COURSE_ID="<course ID>" make e2e