# 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](https://gitlab.com/leap-dojo/leap_salesforce/badges/master/build.svg)](https://gitlab.com/leap-dojo/leap_salesforce/pipelines)

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

## Installation

Add this line to your application's Gemfile:

```ruby
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]('https://gitlab.com/leap-dojo/leap_salesforce/wikis/SetUpOAuthApp').

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](https://asciinema.org/a/259098).

### Understanding how things work
 
#### Important files

To see how things fit together, look at the [structure](#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

```ruby
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:

```ruby
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.

```ruby
# 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](https://www.rubydoc.info/gems/leap_salesforce)

## 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](https://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](http://contributor-covenant.org) code of conduct.

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## 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](https://gitlab.com/leap-dojo/leap_salesforce/blob/master/CODE_OF_CONDUCT.md).

# Examples

See [spec/integration](spec/integration) folder for examples of tests.  

```ruby
# 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](https://gitpitch.com/leap-dojo/leap_salesforce?grs=gitlab)