README.md in leap_salesforce-0.1.8 vs README.md in leap_salesforce-0.1.9
- old
+ new
@@ -5,10 +5,12 @@
In the future it will also planned to be used to create page objects based on metadata to support UI testing.
[](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
@@ -46,22 +48,94 @@
E.g.,
`rake` # Run all tests
-API Traffic logs can be seen in the `logs` folder.
+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)
-TODO: Finish this. A lot more needed
+### 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 #
+ ├── 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
@@ -70,10 +144,10 @@
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 GitHub 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.
+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).