From 895c5085fd6fe8af51b7f487b3b5a383c84519cb Mon Sep 17 00:00:00 2001
From: Bob Wombat Hogg <rhogg@sugarcrm.com>
Date: Wed, 27 Sep 2017 13:52:44 -0700
Subject: [PATCH] Regenerate documentation

Signed-off-by: Bob Wombat Hogg <rhogg@sugarcrm.com>
---
 docs/classes.list.html           | 2 +-
 docs/index.html                  | 4 ++--
 docs/module-thorn-Agent.html     | 2 +-
 docs/module-thorn-Fixtures.html  | 2 +-
 docs/module-thorn-UserAgent.html | 2 +-
 docs/module-thorn.html           | 2 +-
 docs/modules.list.html           | 2 +-
 docs/namespaces.list.html        | 2 +-
 docs/quicksearch.html            | 2 +-
 docs/utils.html                  | 2 +-
 10 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/classes.list.html b/docs/classes.list.html
index 19b5308..c9bdb9e 100644
--- a/docs/classes.list.html
+++ b/docs/classes.list.html
@@ -222,7 +222,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/index.html b/docs/index.html
index 0ff4ea9..4b2517a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -268,7 +268,7 @@ <h4><strong><code>Fixtures.link(left, linkName, right)</code> =&gt; <code>{Promi
 let cachedRecords = yield Fixtures.create([Account, Contact]);
 console.log(cachedRecords); // Map containing one Account and one Contact
 
-let response = yield Fixtures.link(cachedRecords.Accounts[0], 'accounts_contacts', cachedRecords.Contacts[0]);
+let response = yield Fixtures.link(cachedRecords.Accounts[0], 'contacts', cachedRecords.Contacts[0]);
 // Server response containing the Accounts record and a `related_records` property,
 // which contains the Contacts record.
 console.log(response);
@@ -515,7 +515,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-thorn-Agent.html b/docs/module-thorn-Agent.html
index 7ae20eb..d78ae5f 100644
--- a/docs/module-thorn-Agent.html
+++ b/docs/module-thorn-Agent.html
@@ -415,7 +415,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-thorn-Fixtures.html b/docs/module-thorn-Fixtures.html
index 979ef50..105160d 100644
--- a/docs/module-thorn-Fixtures.html
+++ b/docs/module-thorn-Fixtures.html
@@ -951,7 +951,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-thorn-UserAgent.html b/docs/module-thorn-UserAgent.html
index 705b29a..4abdb19 100644
--- a/docs/module-thorn-UserAgent.html
+++ b/docs/module-thorn-UserAgent.html
@@ -1378,7 +1378,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-thorn.html b/docs/module-thorn.html
index c372850..d5b1a7d 100644
--- a/docs/module-thorn.html
+++ b/docs/module-thorn.html
@@ -216,7 +216,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/modules.list.html b/docs/modules.list.html
index de11088..dac31e2 100644
--- a/docs/modules.list.html
+++ b/docs/modules.list.html
@@ -222,7 +222,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/namespaces.list.html b/docs/namespaces.list.html
index 47a3248..9f40743 100644
--- a/docs/namespaces.list.html
+++ b/docs/namespaces.list.html
@@ -222,7 +222,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/quicksearch.html b/docs/quicksearch.html
index fc53986..dadd611 100644
--- a/docs/quicksearch.html
+++ b/docs/quicksearch.html
@@ -7,7 +7,7 @@
     <script src="scripts/fulltext-search.js"></script>
 
     <script type="text/x-docstrap-searchdb">
-    {"modules.list.html":{"id":"modules.list.html","title":"Modules","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Modules Classes UserAgent Namespaces Agent Fixtures utils × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "},"classes.list.html":{"id":"classes.list.html","title":"Classes","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Classes Classes UserAgent Namespaces Agent Fixtures utils × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "},"namespaces.list.html":{"id":"namespaces.list.html","title":"Namespaces","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Namespaces Classes UserAgent Namespaces Agent Fixtures utils × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "},"index.html":{"id":"index.html","title":"Index","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent ThornThorn is composed of a set of helper abstractions built to ease the process of setting up a SugarCRM's REST API testing environment and interacting with it. PrerequisitesYou should be familiar with mocha and JavaScript Promises. Installation and RunningThorn tests are run using the Mocha test runner. To add Thorn as a dependency, run $ yarn add --dev '@sugarcrm/thorn'You will need to invoke Mocha in order to run Thorn. Check out Mocha's usage information, grunt-mocha, and gulp-spawn-mocha for information about instantiating Mocha. Setupconst {Agent, Fixtures} = require('@sugarcrm/thorn');Thorn.FixturesThorn.Fixtures is an object that handles the setup and cleanup process for test sets. It provides methods for creating records, record-relationships, and deleting records in the database. MethodsFixtures.create(models, options) =&gt; {Promise}Method to create records in the database. Name Type Description models {Object|Object[]} Object or object array that specifies the records to be created. See Model Structure for details. options {Object} Optional, options.module is the default module for objects in models that do not specify one. Returns: Type Description {Promise} A Promise which resolves to a map of module names to records created by this method call. Example: let AccountsContacts = [ { module: 'Accounts', attributes: { name: 'MyAccount' } }, { module: 'Contacts', attributes: { first_name: 'FirstName' } } ]; let DashboardsOnly = [ { attributes: { name: 'MyDashboard' } } ]; let response = yield Fixtures.create(AccountsContacts); console.log(response); // Map containing one account, and one contact /* { Accounts: [ { id: '12257c7c-bb40-11e6-afb2-a0937b020fc9', name: 'MyAccount', ... _module: 'Accounts' } ], Contacts: [ { id: '11232c7c-bb40-11e6-bfb2-a0937b020sc9', first_name: 'FirstName' ... _module: 'Contacts' } ] } */ response = yield Fixtures.create(DashboardsOnly, {module: 'Dashboards'}); console.log(response); /* { Dashboards: [ { id: '11232c7c-bb40-11e6-bfb2-a0937b020sc9', name: 'MyDashboard', ... _module: 'Dashboards' } ] } */ Fixtures.link(left, linkName, right) =&gt; {Promise}Method to link records in the database. Name Type Description left {Object} A record from the resolution of Fixtures.create. linkName {string} Relationship's link name. right {Object} A record from the resolution of Fixtures.create. Returns: Type Description {Promise} A Promise which resolves to the body of the server response. Example: let Account = { module: 'Accounts', attributes: { name: 'LinkedAccount' } }; let Contact = { module: 'Contacts', attributes: { last_name: 'LinkedContact' } }; let cachedRecords = yield Fixtures.create([Account, Contact]); console.log(cachedRecords); // Map containing one Account and one Contact let response = yield Fixtures.link(cachedRecords.Accounts[0], 'accounts_contacts', cachedRecords.Contacts[0]); // Server response containing the Accounts record and a `related_records` property, // which contains the Contacts record. console.log(response); /* { record: { id: '12257c7c-bb40-11e6-afb2-a0937b020fc9', name: 'LinkedAccount', ... _module: 'Accounts' }, related_records: [ { id: '12557c7c-bd40-11e6-afb2-a0345b020fc9', last_name: 'LinkedContact', ... _module: 'Contacts' } ] } */ Fixtures.cleanup() =&gt; {Promise}Method to delete all records previously created through Fixtures.create. After cleanup, Fixtures.lookup will throw an error unless more records are created with Fixtures.create. Returns: Type Description {Promise} A Promise which resolves to the server response to the delete request(s). Fixtures.lookup(module, properties) =&gt; {Object}Method that looks through the created records and retrieves the first record that matches module and the key-value pairs in properties. Name Type Description module {string} Module name of the record. properties {Object} Object of key-value pairs the record should contain. Returns: Type Description {Object} A single record object. Model StructureModels is an object or array of objects that specifies the records the tester intends to create. Properties of each model object: Name Type Description module {string} Optional, module name of the record. attributes {Object} Specific fields the record should have. Unspecified required field values are auto-generated. Tips Fixtures is designed to be a tool that facilitates the setup and cleanup of test cases. Its methods are not meant to provide a means of testing the correctness of SugarCRM's record creation, linking, and deletion APIs. Such tests should make use of the request methods of UserAgent. The same model object cannot be used to create multiple records; this will lead to collisions in Fixtures internal ways of storing records. To reuse the same model to create multiple records, all but the first model must be cloned ( e.g. using _.clone). Linking records requires that the records have already been created in the database. To avoid exceptions, structure the record creations such that dependencies are met before Fixtures tries to make links. Thorn.AgentThorn provides an Agent class that simulates a REST API user agent. You should use this class for all of your Thorn tests except those which test the Users API directly (in which case you should use the chakram API directly). Creating AgentsAn Agent corresponds directly to a user that exists in the SugarCRM instance you are testing. All users except for the admin user specified by the THORN_ADMIN_USERNAME environment variable must be created by Fixtures.create before you attempt to create a user agent for it. Please refer to Thorn Fixtures API to create the needed users. User agents are created with Agent.as: // assuming a user named &quot;John&quot; already exists let john = Agent.as('John');This also logs the user in if they have not been logged in already. Default admin userYou can retrieve the user agent corresponding to the default admin user with Agent.as(Agent.ADMIN). The default admin user should not be accessed by name, nor be created with Fixtures.create. let badAdmin = Agent.as('admin'); // Don't do this let goodAdmin = Agent.as(Agent.ADMIN);This ensures that the admin user can be used even on Sugar instances where the admin username is not &quot;admin&quot;. Making requestsAgents can make HTTP GET, POST, PUT, and DELETE requests against any SugarCRM REST API endpoint. Each request method has a corresponding function, which makes the desired request and returns a JavaScript Promise which resolves to a Chakram response object corresponding to the server's response to the request: let response = yield john.get('Accounts'); console.log('%j', response.response.body); // displays response bodyRequired user refreshes are handled automatically by an agent. If a request fails with HTTP status 401, the agent's authentication is refreshed and the request is automatically retried. However, each request is only retried once to prevent infinite loops. Request Methodsgetlet response = yield john.get('Accounts'); console.log(response.response.body); /* { next_offset: -1, records: [ { id: '12257c7c-bb40-11e6-afb2-a0999b020fc9', name: 'Accounts.Samantha', date_entered: '2016-12-05T15:10:53-08:00', date_modified: '2016-12-05T15:10:53-08:00', ... _module: 'Accounts' }, ... ] */postlet response = yield john.post('Accounts', {name: 'Smith'}); console.log(response.response.body); /* { id: '10e42218-bb41-11e6-82c7-a0999b020fc9', name: 'Smith', date_entered: '2016-12-05T15:18:00-08:00', date_modified: '2016-12-05T15:18:00-08:00', ... } */put// assuming &quot;id&quot; is the the ID of Smith let response = yield john.put('Accounts/' + id, {industry: 'Not For Profit'}); console.log(response.response.body); /* { id: '10e42218-bb41-11e6-82c7-a0999b020fc9', name: 'Smith', date_entered: '2016-12-05T15:54:26-08:00', date_modified: '2016-12-05T15:54:27-08:00', industry: 'Not For Profit', ... } */deletelet response = yield john.delete('Accounts' + id); console.log(response.response.body); /* {id: '10e42218-bb41-11e6-82c7-a0999b020fc9'} */Request ArgumentsAll request methods accept an endpoint and HTTP request parameters; Agent.put, Agent.post, and Agent.delete additionally accept a request body. EndpointsEndpoints are specified relative to /rest/&lt;version&gt;/ (see API versioning), so example endpoints might be 'Accounts', 'Contacts/&lt;contactId&gt;', or 'Forecasts/&lt;timePeriodId&gt;/progressRep/&lt;userId&gt;'. Request BodiesRequest bodies must be JSON-serializable JavaScript objects. They are passed directly to the SugarCRM server. ParametersSee the parameter documentation for details of possible parameters. It is NOT necessary to explicitly include OAuth tokens or other authentication details in your requests; this is handled transparently by Thorn. Attempting to do so may interfere with Thorn's proper operation. API versioningAgents make requests against the default API version (currently, v10) by default. To make requests against a different API version, use Agent.on: let johnV11 = john.on('v11'); // all requests made against API version 11 let response = yield johnV11.get('Dashboards'); ... let response = yield johnV11.get('KBContents'); ...Note that the original Agent remains valid and can continue to make requests against the default API version with no additional effort: let response = yield john.get('Notifications') ...Best Practices Every test file should be wrapped in a describe block to protect against cross-test contamination. In the before and after functions, as well as in Promise chains, every Promise created must be returned in order for server requests to effectuate. Not returning Promises could lead to test failures and false positives. Debugging TestsWhile developing or debugging a test, you can set the environment variable THORN_VERBOSE to enable verbose output from Thorn. Users of Thorn seeking to debug their tests should set THORN_VERBOSE=1. THORN_VERBOSE=2 is intended for those developing Thorn itself and is not intended for users. Before commiting tests, please ensure you run them with THORN_VERBOSE=1 so you can be sure you are making the HTTP requests and getting the responses back that you expect. × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "},"module-thorn.html":{"id":"module-thorn.html","title":"Module: thorn","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Module: thorn Thorn Node.js module for REST API testing SugarCRM with Chakram. Classes UserAgent Namespaces Agent Fixtures × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "},"module-thorn-Agent.html":{"id":"module-thorn-Agent.html","title":"Namespace: Agent","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Namespace: Agent thorn~ Agent Namespace for UserAgent access methods. Properties: Name Type Description ADMIN string Username for the SugarCRM administrative user. Methods &lt;static&gt; as(username) Return a UserAgent with the given user name and log them in. Parameters: Name Type Description username string Username of the user agent. Returns: A UserAgent corresponding to the user with the given username. Type UserAgent × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "},"module-thorn-Fixtures.html":{"id":"module-thorn-Fixtures.html","title":"Namespace: Fixtures","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Namespace: Fixtures thorn~ Fixtures Fixtures for pre-creating records. Methods &lt;static&gt; cleanup() Removes all cached records from the server. Additionally, clears the local cache. Returns: The ChakramResponse for the delete request to the server. Type Promise &lt;static&gt; create(models [, options]) Using the supplied models, create records and links on the server and cache those records locally. Parameters: Name Type Argument Description models Object | Array.&lt;Object&gt; An object or array of objects. Each object contains a list of attributes for each new model. options Object &lt;optional&gt; Additional information about models. Properties Name Type Argument Description module string &lt;optional&gt; The module of all models (if not specified in the models' object). Returns: The ChakramResponse from the creation of the records and/or links Type Promise &lt;static&gt; link(left, linkName, right) Creates link between left and right in the database. Parameters: Name Type Description left Object Record retrieved from cache. linkName string Relationship link name. right Object Record retrieved from cache. Returns: The result of the request to link the records. Type ChakramPromise &lt;static&gt; lookup(module, properties) Mimics _.find and using the supplied arguments, returns the cached record. Parameters: Name Type Description module string The module of the record to find. properties Object The properties to search for. Returns: The first record in cachedRecords that matches properties. Type Object × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "},"module-thorn-UserAgent.html":{"id":"module-thorn-UserAgent.html","title":"Class: UserAgent","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Class: UserAgent thorn~ UserAgent Class simulating a web browser user. new UserAgent(username, password, version) Create a new UserAgent. Parameters: Name Type Description username string User name. password string Password. version string API version. Methods delete(endpoint [, data] [, params]) Perform a DELETE request as this user. Parameters: Name Type Argument Description endpoint string API endpoint to make the request to. data Object &lt;optional&gt; DELETE body. params Object &lt;optional&gt; Request parameters. Returns: A promise which resolves to the Chakram DELETE response. Type ChakramPromise get(endpoint [, params]) Perform a GET request as this user. Parameters: Name Type Argument Description endpoint string API endpoint to make the request to. params Object &lt;optional&gt; Request parameters. Returns: A promise which resolves to the Chakram GET response. Type ChakramPromise on(version) Returns a user agent with the same username and password as this one, with the given version. If such an agent does not exist, clone this one. Parameters: Name Type Description version string API version to use. Returns: A UserAgent set to use the given API version. Type UserAgent post(endpoint, data [, params]) Perform a POST request as this user. Parameters: Name Type Argument Description endpoint string API endpoint to make the request to. data Object POST body. params Object &lt;optional&gt; Request parameters. Returns: A promise which resolves to the Chakram POST response. Type ChakramPromise put(endpoint, data [, params]) Perform a PUT request as this user. Parameters: Name Type Argument Description endpoint string API endpoint to make the request to. data Object PUT body. params Object &lt;optional&gt; Request parameters. Returns: A promise which resolves to the Chakram PUT response. Type ChakramPromise × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "},"utils.html":{"id":"utils.html","title":"Namespace: utils","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Namespace: utils utils Thorn-private utility functions. Methods &lt;static&gt; assertSaneResponse(response) Ensure that a Chakram response object is sane before using it. Throws an error if the response is unreasonable. Parameters: Name Type Description response ChakramResponse Object to check. &lt;static&gt; constructUrl(pathParts) Construct a URL relative to the base URL. Each argument is joined with a /. Parameters: Name Type Argument Description pathParts string &lt;repeatable&gt; URL path component. Returns: The full URL. Type string &lt;static&gt; login(options) Log in as any user. Parameters: Name Type Description options Object Login options. Properties Name Type Description username string Username of the user to log in as. password string Password of the user to log in as. version string API version to use to log in. xthorn string Value of the X-Thorn header. Returns: Promise that resolves to the result of the login request. Type ChakramPromise &lt;static&gt; refresh(options) Refresh the user with the given refresh token. Parameters: Name Type Description options Object Refresh options. Properties Name Type Description version string API version to do the refresh request on. token string The refresh token of the user you wish to refresh. xthorn string Value of the X-Thorn header. Returns: A promise which resolves to the Chakram refresh response. Type ChakramPromise &lt;static&gt; wrapRequest(chakramMethod, args, options) Tries a request. If it fails because of HTTP 401, do a refresh and then try again. If it fails because of some other HTTP status code, throw an exception. Parameters: Name Type Description chakramMethod function Chakram request method to call. args Array Arguments to call the chakram request method with. The last member of the array must be a params-like object. options Object Additional configuration options. Properties Name Type Description refreshToken string Refresh token to use if you have to do a refresh. afterRefresh function Additional tasks to be performed after a refresh occurs. Passed the chakram response object from the refresh. retryVersion string API version to make the retry request on. Non-retry requests are made on whatever version is specified by args. xthorn string Value of the X-Thorn header. Returns: A promise resolving to the result of the request. If the first try failed, it will resolve to the result of the second, whether it succeeded or not. Type ChakramPromise × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:23:44-07:00 using the DocStrap template. "}}
+    {"modules.list.html":{"id":"modules.list.html","title":"Modules","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Modules Classes UserAgent Namespaces Agent Fixtures utils × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "},"classes.list.html":{"id":"classes.list.html","title":"Classes","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Classes Classes UserAgent Namespaces Agent Fixtures utils × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "},"namespaces.list.html":{"id":"namespaces.list.html","title":"Namespaces","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Namespaces Classes UserAgent Namespaces Agent Fixtures utils × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "},"index.html":{"id":"index.html","title":"Index","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent ThornThorn is composed of a set of helper abstractions built to ease the process of setting up a SugarCRM's REST API testing environment and interacting with it. PrerequisitesYou should be familiar with mocha and JavaScript Promises. Installation and RunningThorn tests are run using the Mocha test runner. To add Thorn as a dependency, run $ yarn add --dev '@sugarcrm/thorn'You will need to invoke Mocha in order to run Thorn. Check out Mocha's usage information, grunt-mocha, and gulp-spawn-mocha for information about instantiating Mocha. Setupconst {Agent, Fixtures} = require('@sugarcrm/thorn');Thorn.FixturesThorn.Fixtures is an object that handles the setup and cleanup process for test sets. It provides methods for creating records, record-relationships, and deleting records in the database. MethodsFixtures.create(models, options) =&gt; {Promise}Method to create records in the database. Name Type Description models {Object|Object[]} Object or object array that specifies the records to be created. See Model Structure for details. options {Object} Optional, options.module is the default module for objects in models that do not specify one. Returns: Type Description {Promise} A Promise which resolves to a map of module names to records created by this method call. Example: let AccountsContacts = [ { module: 'Accounts', attributes: { name: 'MyAccount' } }, { module: 'Contacts', attributes: { first_name: 'FirstName' } } ]; let DashboardsOnly = [ { attributes: { name: 'MyDashboard' } } ]; let response = yield Fixtures.create(AccountsContacts); console.log(response); // Map containing one account, and one contact /* { Accounts: [ { id: '12257c7c-bb40-11e6-afb2-a0937b020fc9', name: 'MyAccount', ... _module: 'Accounts' } ], Contacts: [ { id: '11232c7c-bb40-11e6-bfb2-a0937b020sc9', first_name: 'FirstName' ... _module: 'Contacts' } ] } */ response = yield Fixtures.create(DashboardsOnly, {module: 'Dashboards'}); console.log(response); /* { Dashboards: [ { id: '11232c7c-bb40-11e6-bfb2-a0937b020sc9', name: 'MyDashboard', ... _module: 'Dashboards' } ] } */ Fixtures.link(left, linkName, right) =&gt; {Promise}Method to link records in the database. Name Type Description left {Object} A record from the resolution of Fixtures.create. linkName {string} Relationship's link name. right {Object} A record from the resolution of Fixtures.create. Returns: Type Description {Promise} A Promise which resolves to the body of the server response. Example: let Account = { module: 'Accounts', attributes: { name: 'LinkedAccount' } }; let Contact = { module: 'Contacts', attributes: { last_name: 'LinkedContact' } }; let cachedRecords = yield Fixtures.create([Account, Contact]); console.log(cachedRecords); // Map containing one Account and one Contact let response = yield Fixtures.link(cachedRecords.Accounts[0], 'contacts', cachedRecords.Contacts[0]); // Server response containing the Accounts record and a `related_records` property, // which contains the Contacts record. console.log(response); /* { record: { id: '12257c7c-bb40-11e6-afb2-a0937b020fc9', name: 'LinkedAccount', ... _module: 'Accounts' }, related_records: [ { id: '12557c7c-bd40-11e6-afb2-a0345b020fc9', last_name: 'LinkedContact', ... _module: 'Contacts' } ] } */ Fixtures.cleanup() =&gt; {Promise}Method to delete all records previously created through Fixtures.create. After cleanup, Fixtures.lookup will throw an error unless more records are created with Fixtures.create. Returns: Type Description {Promise} A Promise which resolves to the server response to the delete request(s). Fixtures.lookup(module, properties) =&gt; {Object}Method that looks through the created records and retrieves the first record that matches module and the key-value pairs in properties. Name Type Description module {string} Module name of the record. properties {Object} Object of key-value pairs the record should contain. Returns: Type Description {Object} A single record object. Model StructureModels is an object or array of objects that specifies the records the tester intends to create. Properties of each model object: Name Type Description module {string} Optional, module name of the record. attributes {Object} Specific fields the record should have. Unspecified required field values are auto-generated. Tips Fixtures is designed to be a tool that facilitates the setup and cleanup of test cases. Its methods are not meant to provide a means of testing the correctness of SugarCRM's record creation, linking, and deletion APIs. Such tests should make use of the request methods of UserAgent. The same model object cannot be used to create multiple records; this will lead to collisions in Fixtures internal ways of storing records. To reuse the same model to create multiple records, all but the first model must be cloned ( e.g. using _.clone). Linking records requires that the records have already been created in the database. To avoid exceptions, structure the record creations such that dependencies are met before Fixtures tries to make links. Thorn.AgentThorn provides an Agent class that simulates a REST API user agent. You should use this class for all of your Thorn tests except those which test the Users API directly (in which case you should use the chakram API directly). Creating AgentsAn Agent corresponds directly to a user that exists in the SugarCRM instance you are testing. All users except for the admin user specified by the THORN_ADMIN_USERNAME environment variable must be created by Fixtures.create before you attempt to create a user agent for it. Please refer to Thorn Fixtures API to create the needed users. User agents are created with Agent.as: // assuming a user named &quot;John&quot; already exists let john = Agent.as('John');This also logs the user in if they have not been logged in already. Default admin userYou can retrieve the user agent corresponding to the default admin user with Agent.as(Agent.ADMIN). The default admin user should not be accessed by name, nor be created with Fixtures.create. let badAdmin = Agent.as('admin'); // Don't do this let goodAdmin = Agent.as(Agent.ADMIN);This ensures that the admin user can be used even on Sugar instances where the admin username is not &quot;admin&quot;. Making requestsAgents can make HTTP GET, POST, PUT, and DELETE requests against any SugarCRM REST API endpoint. Each request method has a corresponding function, which makes the desired request and returns a JavaScript Promise which resolves to a Chakram response object corresponding to the server's response to the request: let response = yield john.get('Accounts'); console.log('%j', response.response.body); // displays response bodyRequired user refreshes are handled automatically by an agent. If a request fails with HTTP status 401, the agent's authentication is refreshed and the request is automatically retried. However, each request is only retried once to prevent infinite loops. Request Methodsgetlet response = yield john.get('Accounts'); console.log(response.response.body); /* { next_offset: -1, records: [ { id: '12257c7c-bb40-11e6-afb2-a0999b020fc9', name: 'Accounts.Samantha', date_entered: '2016-12-05T15:10:53-08:00', date_modified: '2016-12-05T15:10:53-08:00', ... _module: 'Accounts' }, ... ] */postlet response = yield john.post('Accounts', {name: 'Smith'}); console.log(response.response.body); /* { id: '10e42218-bb41-11e6-82c7-a0999b020fc9', name: 'Smith', date_entered: '2016-12-05T15:18:00-08:00', date_modified: '2016-12-05T15:18:00-08:00', ... } */put// assuming &quot;id&quot; is the the ID of Smith let response = yield john.put('Accounts/' + id, {industry: 'Not For Profit'}); console.log(response.response.body); /* { id: '10e42218-bb41-11e6-82c7-a0999b020fc9', name: 'Smith', date_entered: '2016-12-05T15:54:26-08:00', date_modified: '2016-12-05T15:54:27-08:00', industry: 'Not For Profit', ... } */deletelet response = yield john.delete('Accounts' + id); console.log(response.response.body); /* {id: '10e42218-bb41-11e6-82c7-a0999b020fc9'} */Request ArgumentsAll request methods accept an endpoint and HTTP request parameters; Agent.put, Agent.post, and Agent.delete additionally accept a request body. EndpointsEndpoints are specified relative to /rest/&lt;version&gt;/ (see API versioning), so example endpoints might be 'Accounts', 'Contacts/&lt;contactId&gt;', or 'Forecasts/&lt;timePeriodId&gt;/progressRep/&lt;userId&gt;'. Request BodiesRequest bodies must be JSON-serializable JavaScript objects. They are passed directly to the SugarCRM server. ParametersSee the parameter documentation for details of possible parameters. It is NOT necessary to explicitly include OAuth tokens or other authentication details in your requests; this is handled transparently by Thorn. Attempting to do so may interfere with Thorn's proper operation. API versioningAgents make requests against the default API version (currently, v10) by default. To make requests against a different API version, use Agent.on: let johnV11 = john.on('v11'); // all requests made against API version 11 let response = yield johnV11.get('Dashboards'); ... let response = yield johnV11.get('KBContents'); ...Note that the original Agent remains valid and can continue to make requests against the default API version with no additional effort: let response = yield john.get('Notifications') ...Best Practices Every test file should be wrapped in a describe block to protect against cross-test contamination. In the before and after functions, as well as in Promise chains, every Promise created must be returned in order for server requests to effectuate. Not returning Promises could lead to test failures and false positives. Debugging TestsWhile developing or debugging a test, you can set the environment variable THORN_VERBOSE to enable verbose output from Thorn. Users of Thorn seeking to debug their tests should set THORN_VERBOSE=1. THORN_VERBOSE=2 is intended for those developing Thorn itself and is not intended for users. Before commiting tests, please ensure you run them with THORN_VERBOSE=1 so you can be sure you are making the HTTP requests and getting the responses back that you expect. × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "},"module-thorn.html":{"id":"module-thorn.html","title":"Module: thorn","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Module: thorn Thorn Node.js module for REST API testing SugarCRM with Chakram. Classes UserAgent Namespaces Agent Fixtures × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "},"module-thorn-Agent.html":{"id":"module-thorn-Agent.html","title":"Namespace: Agent","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Namespace: Agent thorn~ Agent Namespace for UserAgent access methods. Properties: Name Type Description ADMIN string Username for the SugarCRM administrative user. Methods &lt;static&gt; as(username) Return a UserAgent with the given user name and log them in. Parameters: Name Type Description username string Username of the user agent. Returns: A UserAgent corresponding to the user with the given username. Type UserAgent × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "},"module-thorn-Fixtures.html":{"id":"module-thorn-Fixtures.html","title":"Namespace: Fixtures","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Namespace: Fixtures thorn~ Fixtures Fixtures for pre-creating records. Methods &lt;static&gt; cleanup() Removes all cached records from the server. Additionally, clears the local cache. Returns: The ChakramResponse for the delete request to the server. Type Promise &lt;static&gt; create(models [, options]) Using the supplied models, create records and links on the server and cache those records locally. Parameters: Name Type Argument Description models Object | Array.&lt;Object&gt; An object or array of objects. Each object contains a list of attributes for each new model. options Object &lt;optional&gt; Additional information about models. Properties Name Type Argument Description module string &lt;optional&gt; The module of all models (if not specified in the models' object). Returns: The ChakramResponse from the creation of the records and/or links Type Promise &lt;static&gt; link(left, linkName, right) Creates link between left and right in the database. Parameters: Name Type Description left Object Record retrieved from cache. linkName string Relationship link name. right Object Record retrieved from cache. Returns: The result of the request to link the records. Type ChakramPromise &lt;static&gt; lookup(module, properties) Mimics _.find and using the supplied arguments, returns the cached record. Parameters: Name Type Description module string The module of the record to find. properties Object The properties to search for. Returns: The first record in cachedRecords that matches properties. Type Object × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "},"module-thorn-UserAgent.html":{"id":"module-thorn-UserAgent.html","title":"Class: UserAgent","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Class: UserAgent thorn~ UserAgent Class simulating a web browser user. new UserAgent(username, password, version) Create a new UserAgent. Parameters: Name Type Description username string User name. password string Password. version string API version. Methods delete(endpoint [, data] [, params]) Perform a DELETE request as this user. Parameters: Name Type Argument Description endpoint string API endpoint to make the request to. data Object &lt;optional&gt; DELETE body. params Object &lt;optional&gt; Request parameters. Returns: A promise which resolves to the Chakram DELETE response. Type ChakramPromise get(endpoint [, params]) Perform a GET request as this user. Parameters: Name Type Argument Description endpoint string API endpoint to make the request to. params Object &lt;optional&gt; Request parameters. Returns: A promise which resolves to the Chakram GET response. Type ChakramPromise on(version) Returns a user agent with the same username and password as this one, with the given version. If such an agent does not exist, clone this one. Parameters: Name Type Description version string API version to use. Returns: A UserAgent set to use the given API version. Type UserAgent post(endpoint, data [, params]) Perform a POST request as this user. Parameters: Name Type Argument Description endpoint string API endpoint to make the request to. data Object POST body. params Object &lt;optional&gt; Request parameters. Returns: A promise which resolves to the Chakram POST response. Type ChakramPromise put(endpoint, data [, params]) Perform a PUT request as this user. Parameters: Name Type Argument Description endpoint string API endpoint to make the request to. data Object PUT body. params Object &lt;optional&gt; Request parameters. Returns: A promise which resolves to the Chakram PUT response. Type ChakramPromise × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "},"utils.html":{"id":"utils.html","title":"Namespace: utils","body":" Documentation Namespaces thorn~Agentthorn~Fixturesutils Modules thorn Classes thorn~UserAgent Namespace: utils utils Thorn-private utility functions. Methods &lt;static&gt; assertSaneResponse(response) Ensure that a Chakram response object is sane before using it. Throws an error if the response is unreasonable. Parameters: Name Type Description response ChakramResponse Object to check. &lt;static&gt; constructUrl(pathParts) Construct a URL relative to the base URL. Each argument is joined with a /. Parameters: Name Type Argument Description pathParts string &lt;repeatable&gt; URL path component. Returns: The full URL. Type string &lt;static&gt; login(options) Log in as any user. Parameters: Name Type Description options Object Login options. Properties Name Type Description username string Username of the user to log in as. password string Password of the user to log in as. version string API version to use to log in. xthorn string Value of the X-Thorn header. Returns: Promise that resolves to the result of the login request. Type ChakramPromise &lt;static&gt; refresh(options) Refresh the user with the given refresh token. Parameters: Name Type Description options Object Refresh options. Properties Name Type Description version string API version to do the refresh request on. token string The refresh token of the user you wish to refresh. xthorn string Value of the X-Thorn header. Returns: A promise which resolves to the Chakram refresh response. Type ChakramPromise &lt;static&gt; wrapRequest(chakramMethod, args, options) Tries a request. If it fails because of HTTP 401, do a refresh and then try again. If it fails because of some other HTTP status code, throw an exception. Parameters: Name Type Description chakramMethod function Chakram request method to call. args Array Arguments to call the chakram request method with. The last member of the array must be a params-like object. options Object Additional configuration options. Properties Name Type Description refreshToken string Refresh token to use if you have to do a refresh. afterRefresh function Additional tasks to be performed after a refresh occurs. Passed the chakram response object from the refresh. retryVersion string API version to make the retry request on. Non-retry requests are made on whatever version is specified by args. xthorn string Value of the X-Thorn header. Returns: A promise resolving to the result of the request. If the first try failed, it will resolve to the result of the second, whether it succeeded or not. Type ChakramPromise × Search results Close Documentation generated by JSDoc 3.4.3 on 2017-09-27T13:51:56-07:00 using the DocStrap template. "}}
     </script>
 
     <script type="text/javascript">
diff --git a/docs/utils.html b/docs/utils.html
index cf134df..eacb7c9 100644
--- a/docs/utils.html
+++ b/docs/utils.html
@@ -1354,7 +1354,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
 	
-		on 2017-09-27T13:23:44-07:00
+		on 2017-09-27T13:51:56-07:00
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>