This CLI is deprecated. For a more feature-rich CLI, see datatrue-cli

DataTrue API client

DataTrue is a SaaS platform to audit, monitor and validate tags, dataLayers and data collected from websites. The DataTrue Test Builder chrome extension can quickly create test interactions with websites using our library of 100+ tag templates or custom tags. DataTrue works across complex AJAX interactions (e.g. using AngularJS), iframe content and multiple domains.

This ruby client allows you to trigger DataTrue tests from a Continuous Integration tool such as Jenkins, Teamcity, Travis CI, Codeship and others. If you’re practicing Continuous Delivery, it can be used to trigger a test of your application as soon as changes are released.

Table of Contents

• DataTrue API client
  • Table of Contents
  • Usage
    • Command-line usage
      • Environment variables
    • Usage in a Ruby application
  • Support
  • Contributing
    • Development
  • License

Usage

You will need a DataTrue account (free sign-up) to use this gem. To get your API key go to the Accounts page, select your account and click on "Generate API Key".

The next steps assume you have a test suite created in DataTrue. Read our Knowledge Base to find-out how to quickly create a single-page test.

Install the gem on the system you want to trigger your tests from:

$ gem install datatrue_client

Alternatively, if you want to include the client as part of your ruby application, you can add this line to your Gemfile:

gem 'datatrue_client', :group => [:test, :development]

Command-line usage

Use the following CLI syntax to select your test(s) or test suite along with other options.

$ datatrue_client run 1539 -a rtTlaqucG9RrTg1G2L1O0u -t suite \
    -v HOSTNAME=datatrue.com,GTMID=GTM-ABCXYZ \
    -e 543,544

datatrue_client: job=5e9316aa116b4a6fe5dfebda68accd60 created for test="DataTrue Public pages"
datatrue_client: test_run_id=52454 step=1 total_steps=7 result=running
datatrue_client: test_run_id=52454 step=1 total_steps=7 result=passed
...
datatrue_client: test_run_id=52454 step=7 total_steps=7 result=passed
datatrue_client: test_run_id=52454 finished result=passed.

The exit status of the application will change according to test results:

• 0: test run successful, result=passed.
• 1: test run successful, result=failed.
• -1: generic test run error. See output detail.
• -2: authentication or authorisation error. Check your API key and test identifiers.
• -3: quota exceeded. You have used-up all your subscription allowance for this period.

If you want to ignore the exit status, use the shell's || operator; e.g.: datatrue_client [options] || true. This will ensure that the exit status is always 0.

datatrue_client <command> [command-arguments] -a <api_key> [command-options]

Commands:

• run: triggers a new run of tests or a test suite and waits for it to finish.

datatrue_client run <suite_id | test_id_1,test_id_2,...> -a <api_key>
    [-t | --type=suite|test] [-v | --variables foo=bar,thunder=flash]
    [-e | --email-users '1,2,3...'] [-s | --silent]

• trigger: triggers a new run of tests or a test suite and exits immediately.

datatrue_client trigger <suite_id | test_id_1,test_id_2,...> -a <api_key>
    [-t | --type=suite|test] [-v | --variables foo=bar,thunder=flash]
    [-s | --silent]

Options:

• -a or --api-key: The DataTrue API key. Overrides the API key provided as an environment variable.
• -t or --type: The type of test to be run. Valid options are test or suite.
• -v or --variables: Variables provided to the test. These can be used to change behaviour of your test, provide credentials and more.
• -e or --email-users: Comma-separated list of user identifiers who will receive an email with the test results.
• -s or --silent: Suppress all application output.
• -h or --help: Show help message.

Specific options for run:

• --timeout: Time to wait before the run finishes.

Environment variables

• DATATRUE_API_KEY: your DataTrue API key. The -a option takes precedence.

Usage in a Ruby application

Trigger a test run:

test_run = DatatrueClient::TestRun.new({
  host: 'localhost:3000',
  scheme: 'http',
  api_key: '_AHQZRHZ3kD0kpa0Al-SJg',  # please remember to generate your own key on datatrue.com

  test_run: {
    test_class: 'TestScenario',
    test_id: 1
  },
  variables: {
    key: value
  },

  polling_interval: 2,  # in seconds, 2 by default
  polling_timeout: 120  # in seconds, 60 by default
})

Query progress:

test_run.query_progress

# returns the progress hash
#
# {
#   time: 1463359905,
#   status: "running",
#   uuid: "a1f7868b1db44d38c16585ce37e4ac3f",
#   num: 4,
#   total: 5,
#   progress: {
#     percentage: 80,
#     steps_total: 4,
#     tests: [
#       {
#         id: 1,
#         name: "Test name",
#         state: "running",
#         actions_completed: 4,
#         actions_total: 5,
#         steps: [
#           {
#             name: "Step name",
#             running: false,
#             pending: false,
#             error: nil,
#             tags: [
#               { name: "Tag name', enabled: true, valid: true },
#               ...
#             ]
#           },
#           ...
#         ]
#       },
#       ...
#     ]
#   }
# }

Poll progress (blocks until the run is finished or timed out):

test_run.poll_progress

Support

Our support website has more detailed information about DataTrue and the API client.

If you believe you have found a bug, please reach-out using the support website or through support@datatrue.com.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/datatrue-analytics/datatrue-api-client.

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.

License

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