Search

    Hybrid Testing

    Introduction

    You can easily test your CAP application using a local database and mocks. But at some point of time, you want to test with real cloud services. Of course, you can deploy your application to the cloud.

    With the hybrid testing capabilities, you stay in your local development environment and avoid long turn-around times of cloud deployment and you can selectively decide which services you want to use from the cloud.

    Use the cds bind command to connect your application to services on the cloud. Start your application with the hybrid profile to use these service bindings. You can switch between local mocking configuration and cloud service configuration, by just setting or omitting the profile parameter.

    Bind to Cloud Services

    Bind a Local Application to Services on Cloud Foundry

    cds bind -2 my-hana:my-hana-key
    

    Binds your CAP application to the service key my-hana-key for the service instance my-hana using your currently targeted Cloud Foundry space.

    Output:

    [bind] - Retrieving data from Cloud Foundry...
    [bind] - Binding db to Cloud Foundry service cpapp-db key cpapp-db-key with kind hana.
    [bind] - Saving bindings to .cdsrc-private.json in profile hybrid .
    [bind] -
    [bind] - TIP: Run with cloud bindings: cds watch --profile hybrid
    

    The service key needs to be created beforehand.

    You can omit :my-hana-key here, because the key name is just the name of the instance with -key added.

    In many cases CAP knows which CDS service and kind to use for a cloud service. Like in the previous example, the CDS service db gets bound and set to kind hana, because the given service instance is of type hana with plan hdi-shared.

    The binding information is stored in the .cdsrc-private.json file of your project in the requires section:

    {
      "requires": {
        "[hybrid]": {
          "db": {
            "kind": "hana",
            "binding": {
              "type": "cf",
              "apiEndpoint": "https://api.sap.hana.ondemand.com",
              "org": "your-cf-org",
              "space": "your-cf-space",
              "instance": "my-hana",
              "key": "my-hana-key",
              "vcap": {
                "label": "hana",
                "plan": "hdi-shared"
              },
              "resolved": false
            }
          }
        }
      }
    }
    

    Bindings are assigned to the hybrid profile by default.

    Note that no credentials are saved. Only the information where the credentials can be obtained is stored on your machine.

    All cds bind command line options

    Bind a Local Application to Services on Kubernetes

    Not supported yet

    Run with Service Bindings

    Run CAP Node.js Apps with Service Bindings

    Now, you can run your CAP service locally using the cloud service bindings:

    cds watch --profile hybrid
    

    It will resolve the cloud bindings in your configuration with the bound instance and key, by downloading it from the bound Cloud Foundry org and space. This requires that you’re logged in to the Cloud Foundry API endpoint, which has been used to do the binding.

    You can also resolve and display credentials using the cds env command:

    cds env get requires.db.credentials --profile hybrid --resolve-bindings
    

    Example output:

    {
      url: 'jdbc:sap://BDB9AC0F20CB46B494E6742047C4F99A.hana.eu10.hanacloud.ondemand.com:443?encrypt=true&validateCertificate=true&currentschema=BDB9AC0F20CB46B494E6742047C4F99A',
      host: 'bdb9ac0f20cb46b494e6742047c4f99a.hana.eu10.hanacloud.ondemand.com',
      port: '443',
      driver: 'com.sap.db.jdbc.Driver',
      schema: 'BDB9AC0F20CB46B494E6742047C4F99A',
      hdi_user: 'BDB9AC0F20CB46B494E6742047C4F99A_DT',
      hdi_password: 'abc...xyz',
      user: 'BDB9AC0F20CB46B494E6742047C4F99A_RT',
      password: 'abc....xyz',
      certificate: '-----BEGIN CERTIFICATE-----\n' +
        '...' +
        '-----END CERTIFICATE-----'
    }
    

    Only cds watch and cds env (the latter with the --resolve-bindings option) resolve cloud bindings. Bindings are not resolved by cds serve or cds exec.

    Run CAP Java Apps with Service Bindings

    Not supported yet

    Run with Service Bindings from a Running Cloud Application

    Run CAP Apps Using Cloud Application Bindings

    Instead of binding to specific cloud services, you can run your application with all service bindings of an application on the SAP BTP Cloud Foundry environment.

    But you need to have (1) your application deployed and be (2) logged in your Cloud Foundry space using the cf command line.

    For example, you can use the following syntax with bash or similar shells:

    VCAP_SERVICES=$(cf env <CF-APP-NAME> | perl -0pe '/VCAP_SERVICES:(.*?)VCAP_APPLICATION:/smg; $_=$1') cds watch --profile hybrid
    

    Your profile should have the kind settings to use the bound services, for example requires.db = hana.

    cds bind Usage

    By Cloud Service Only

    The shortest form to use cds bind is to specify only the Cloud Foundry service instance name:

    cds bind -2 my-hana
    

    This implies that a service key exists with the suffix -key. In this example: my-hana-key.

    You can specify a different key after a colon (“:”):

    cds bind -2 my-hana:my-different-key
    

    With CDS Service and Kind

    If kind or CDS service cannot be determined automatically by cds bind, you need to specify it:

    cds bind db -2 my-hana --kind hana
    

    You are informed by an error message if this is required.

    Bind Multiple Services with One Command

    There is a handy shortcut to bind multiple services with one command:

    cds bind -2 my-hana,my-destination,my-xsuaa
    

    This shortcut is only possible, if you don’t need to provide a service or a kind.

    With Profile and Output File

    By default the bindings for the profile hybrid are stored in the .cdsrc-private.json file in your current working directory.

    This can be overwritten using the --profile and --output-file options.

    Integration Tests Using Bindings

    cds bind can be handy for testing with real cloud services in your CI/CD pipeline.

    Configure your required bindings for testing and save it to your project’s package.json file for your tests’ profile:

    cds bind -2 integration-test-hana -o package.json -p integration-test
    

    No credentials are saved!

    In your CI/CD pipeline you can resolve the bindings and inject it into the test commands:

    # Install DK for "cds env"
    npm i @sap/cds-dk --no-save
    
    # Login
    cf auth $USER $PASSWORD
    
    ## Uncomment if your service bindings have
    ## no "org" and "space" set (see note below)
    # cf target -o $ORG -s $SPACE
    
    # Set profile
    export CDS_ENV=integration-test
    # Set resolved bindings
    export cds_requires="$(cds env get requires --resolve-bindings)"
    
    # Execute test
    npm run integration-test
    

    With CDS_ENV, you specify the configuration profile for the test, where you put the service binding configuration before.

    cds env get requires prints the requires section of the configuration as a JSON string. By adding the option --resolve-bindings, it includes the credentials of the service bindings from the cloud. To make the credentials available for all subsequent cds commands and the tests, the requires JSON string is put into the cds_requires variable.

    Service bindings created by cds bind contain the Cloud Foundry API endpoint, org, and space. You can allow your services to connect to the currently targeted Cloud Foundry org and space by removing these properties from the binding structure.

    Show/Hide Beta Features