LeapSalesforce

Welcome to LeapSalesforce gem. This gem helps ones to perform integration tests on Salesforce. It reads the Metadata from Salesforce and creates the foundation for API tests.

In the future it will also planned to be used to create page objects based on metadata to support UI testing.

Build Status

Note this documentation is a work in progress. Look at spec for code examples.

Installation

Add this line to your application's Gemfile:

gem 'leap_salesforce'

And then execute:

$ bundle

Or install it yourself as:

$ gem install leap_salesforce

Usage

Getting started

After installing the gem, to get started in creating a fresh repository, the leap_salesforce executable can be used. It will ask for credentials and setup files that will locally store them. This assumes that a Salesforce OAuth app be set up to be used for the API which can be done by following this wiki.

E.g

leap_salesforce init

Credentials are not stored in stored in source control. They can be setting through the following environment variables:

  • 'client_id'
  • 'client_secret'
  • 'password'

Tests can be run using the default Rake task.

E.g.,

rake # Run all tests

API Traffic logs can be seen in the logs folder. You can see an example of running through this here.

Understanding how things work

Important files

To see how things fit together, look at the structure section below.

.leap_salesforce.yml

This YAML file describes common configuration for the project.

Following is a description of each key in this file:

  • environment: Specifies the default environment for this suite. This can be overwritten with the LEAP_ENV environment variable.
  • lib_folder: Can be set to change the default location (lib/leap_salesforce) of where all generated code is put and read from.
  • soql_objects: List of SOQL objects that the generator will create for and update
salesforce_oauth2.yml
  • client_id: OAuth2 client id / customer id obtained from your Test App
  • client_secret: OAuth2 client_secret / customer secret obtained from your Test App
  • password: Password expected to be generic across test users and the same as what's used on the UI to logon with

This file is read and sets attributes of LeapSalesforce globally. These can also be set with the following format

LeapSalesforce.password = 'PASS'
config/general.rb

This is where common code is stored for all the environments. This is where you would usually put your test users as described in the next section.

Test Users

Test users are defined using the LeapSalesforce::Users module. Following is an example of setting up a few test users:

module LeapSalesforce
  # Example where email address changes according to environment
  # Users can be added by passing an array or passing a LeapSalesforce::User object 
  Users.add [:admin, 'admin@<%= LeapSalesforce.environment %>.email.com', description: 'System Admin User']
  Users.add User.new :sales, 'test.sales@test<%= LeapSalesforce.environment %>.com'
end

The first user defined will be the default user. Following users can be set by using the api_user attribute.

# Using key to specify user
LeapSalesforce.api_user = LeapSalesforce::Users.where(key: :sales)
# Using username that has a partial match with a Regex
LeapSalesforce.api_user = LeapSalesforce::Users.where username: /admin/
# Using description that has a partial match with a Regex. This might be helpful if you're setting users from 
# a Cucumber step definition where readability is important 
LeapSalesforce.api_user = LeapSalesforce::Users.where description: /System Admin/

Structure

Following is the general structure of test automation suite that uses this approach. Details may vary depending on the test framework used and other preferences.

.
├──  config                         # Code for the configuration of the automation suite
│   ├── general.rb                  # Code loaded for common (non confidential code) setup across environments
│   ├── credentials                 # Setting of secret properties like passwords
│   │  └── salesforce_oauth2.yml    # Credentials for connecting to Salesforce via OAuth2
│   └── environments                # Contains ruby files loaded specific to environment following `ENVIRONMENT_NAME.rb` 
├──  lib                            # Common library code
│   └── leap_salesforce             # Code generated by or specific to leap_salesforce
│      ├── factories                # FactoryBot definitions, describing how to mass produce objects
│      ├── metadata                 # Code generated and updated automatically from metadata
│      │  └── enum                  # Picklist enumeration objects are stored here 
│      └── soql_data                # Objects for handling each object in the backend specified in '.leap_salesforce.yml'
├──  logs                           # Contains API traffic logs for transactions against Salesforce
├──  spec                           # Where RSpec automated tests are stored
├──  .leap_salesforce.yml           # Where common configuration is stored regarding your project. This complements and is read before what's in 'config'
├──  Gemfile                        # Where required ruby gems/libraries are specified
├──  Gemfile.lock                   # Generated file specified details of versions installed by `Gemfile`
└──  Rakefile                       # Where common `Rake` tasks are specified. LeapSalesforce specific tasks are required from here

Docs

Technical docs here

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitLab at https://gitlab.com/leap-dojo/leap_salesforce. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the LeapSalesforce project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Examples

See spec/integration folder for examples of tests. 

# deleting old contacts
objects = Contact.each_id_with CreatedDate: "<#{5.days.ago}"
puts objects.count
objects.each do |id|
  puts "Deleting #{id}"
  Contact.delete id
end

References

See the presentation on this here