Plugins: Test harness, test fixture, docs, and local-type example #356

clintoncwolfe · 2018-09-27T05:51:08Z

This PR contains few changes to Train itself, but adds many things to the source tree.

A complete (docs, tests, Rakefile, gemspec, implementation) Train plugin example, heavily commented for teaching. This is train-local-rot13; it may make sense to make an additional (but less commented) example for talking to an API.
Under test/fixtures, a test fixture plugin, which responds with fixed responses. It can be used to verify transport loading in Train, or plugin installation capability in InSpec.
Docs under docs/plugins.md, which gives a very high level overview of Train plugin development.
A test support file, lib/train/plugin_test_helper.rb, which helps plugin authors develop against train when writing outside the Train source tree.
Updates the rubocop.yml to permit linting of examples.

Related: inspec/inspec#3444
Related: inspec/inspec#3421

NOTE: until this is merged (and a gem is built), you will need to check out this branch, then locally edit examples/plugins/train-local-rot13/Gemfile to add this line:

# Force bundler to use your source checkout, NOT the rubygems train gem
# TEMPORARY
gem 'train', path: '../path/to/train/source/root'
gemspec

Without this, the example plugin's tests will not be able to find the lib/train/plugin_test_helper.rb (which exists on this branch, not yet in a gem).

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

…ection setup Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

jquick

Thanks @clintoncwolfe ! Nice examples here

jquick · 2018-09-27T13:11:18Z

docs/plugins.md

+
+Required. Use the `name` call to register your plugin.  Pass a String, which should have the 'train-' portion removed.
+
+#### option


These still need filled out I think.

I need help on this - I don't know what is needed. I've filled out a skeleton, with TODOs.

jerryaldrichiii

Looks great @clintoncwolfe, just a few spelling/grammatical things.

You can probably ignore the train-test-fixture feedback...not sure where to put it.

docs/plugins.md

jerryaldrichiii · 2018-09-27T17:11:58Z

docs/plugins.md

+
+### Installing Train Plugins outside of InSpec
+
+If you need a train plugin installed, and `inspec plugin` is not available to you, you can install a train plugin like any other gem.  Just be sure to use the `gem` binary that comes with the application you wish to extend.  For example, to add a Train Plugin to a ChefDK installation, use:


I'm not sure we support adding gems to ChefDK. It is intended to be a bundled distribution.

ChefDK should always have train but the example is fine imo.

I only worry that a user will add a gem and pull in a dep that will break ChefDK in some way.

If deps have issues it should not install and error just like a bundle but retain functionality. If they want to install a new Train on their DevKit that is their call.

docs/plugins.md

examples/plugins/train-local-rot13/test/functional/local-rot13_test.rb

lib/train/plugin_test_helper.rb

test/fixtures/plugins/train-test-fixture/README.md

test/fixtures/plugins/train-test-fixture/lib/train-test-fixture/platform.rb

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Signed-off-by: Jared Quick <jquick@chef.io>

jerryaldrichiii · 2018-09-27T20:37:26Z

docs/plugins.md


 #### local?

-TODO
+This flag helps Train decide what detection to use for OS based platforms. This should be set to `true` if your transport target resides in the same instance you are running train from. This setting is not needed for API transports or transports who do not use platform detection.


I love the anthropomorphism, but might go with that do not use here.

jerryaldrichiii · 2018-09-27T20:37:55Z

docs/plugins.md

+Platform detection is used if you do not specify a platform method for your transport. Currently it is only used for OS (Unix, Windows) platforms. The detection system will run a series of commands on your target to try and determine what platform it is. This information can be found here [OS Specifications](https://github.com/inspec/train/blob/master/lib/train/platforms/detect/specifications/os.rb).
+
+When using a API or a fixed platform for your transport its suggested you skip the detection process and specify a direct platform. Here is an example:


an API? EDIT: Actually I'm not even sure here...English is hard.

it's though I'm sure of 😄

Signed-off-by: Jared Quick <jquick@chef.io>

jquick

Thanks @clintoncwolfe

Signed-off-by: Jared Quick <jquick@chef.io>

clintoncwolfe added 11 commits September 21, 2018 18:46

Rename train-gem-fixture to train-test-fixture

b089042

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Update test fixture plugin to support platform forcing and basic conn…

2a38731

…ection setup Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

First draft of docs and examples

7451be7

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

train-test-fixture feature complete

7d9e779

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Top-level files for train-local-rot13

2f472ee

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Unit tests pass

2a906a9

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Add fixture files

e057109

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Another bonkers plugin helper.

9a03772

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Passing functional tests

5807deb

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Enable using Train project rubocop config

ffa3590

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Linting

d9c6816

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

jquick reviewed Sep 27, 2018

View reviewed changes

jerryaldrichiii suggested changes Sep 27, 2018

View reviewed changes

clintoncwolfe mentioned this pull request Sep 27, 2018

Plugins: Support for Train Plugins in InSpec inspec/inspec#3444

Merged

clintoncwolfe and others added 3 commits September 27, 2018 15:38

PR feedback

1910356

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Correct unit test expected value

f2af2fb

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

Add plugin transport doc info.

c2727ad

Signed-off-by: Jared Quick <jquick@chef.io>

jerryaldrichiii reviewed Sep 27, 2018

View reviewed changes

jquick added 2 commits September 27, 2018 16:55

Fix feedback.

4c8072f

Signed-off-by: Jared Quick <jquick@chef.io>

Fix lint issues. And disable UTF-8 force since its forced on ruby 2.0.

d1f3c07

Signed-off-by: Jared Quick <jquick@chef.io>

jquick approved these changes Sep 27, 2018

View reviewed changes

jerryaldrichiii approved these changes Sep 27, 2018

View reviewed changes

Fix ruby 2.2 heredoc format.

53f56ec

Signed-off-by: Jared Quick <jquick@chef.io>

jquick merged commit 90066d5 into master Sep 27, 2018

jquick deleted the cw/plugins-test-harness branch September 27, 2018 22:24

jquick added the Version: Bump Minor label Sep 27, 2018

clintoncwolfe mentioned this pull request Oct 26, 2018

Document the Connection API #374

Open

clintoncwolfe added Expeditor/Bump Minor Version and removed Version: Bump Minor labels Mar 19, 2019

clintoncwolfe removed the Version: Bump Minor label Mar 19, 2019

zenspider added Expeditor: Bump Minor Version and removed Expeditor/Bump Minor Version labels Nov 15, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Plugins: Test harness, test fixture, docs, and local-type example #356

Plugins: Test harness, test fixture, docs, and local-type example #356

clintoncwolfe commented Sep 27, 2018 •

edited

Loading

jquick left a comment

jquick Sep 27, 2018 •

edited

Loading

clintoncwolfe Sep 27, 2018

jerryaldrichiii left a comment

jerryaldrichiii Sep 27, 2018

clintoncwolfe Sep 27, 2018

jquick Sep 27, 2018

jerryaldrichiii Sep 27, 2018

jquick Sep 27, 2018

jerryaldrichiii Sep 27, 2018

jerryaldrichiii Sep 27, 2018 •

edited

Loading

jerryaldrichiii Sep 27, 2018

jquick left a comment


		Required. Use the `name` call to register your plugin. Pass a String, which should have the 'train-' portion removed.

		#### option


		### Installing Train Plugins outside of InSpec

		If you need a train plugin installed, and `inspec plugin` is not available to you, you can install a train plugin like any other gem. Just be sure to use the `gem` binary that comes with the application you wish to extend. For example, to add a Train Plugin to a ChefDK installation, use:

		Platform detection is used if you do not specify a platform method for your transport. Currently it is only used for OS (Unix, Windows) platforms. The detection system will run a series of commands on your target to try and determine what platform it is. This information can be found here [OS Specifications](https://github.com/inspec/train/blob/master/lib/train/platforms/detect/specifications/os.rb).

		When using a API or a fixed platform for your transport its suggested you skip the detection process and specify a direct platform. Here is an example:

Plugins: Test harness, test fixture, docs, and local-type example #356

Plugins: Test harness, test fixture, docs, and local-type example #356

Conversation

clintoncwolfe commented Sep 27, 2018 • edited Loading

jquick left a comment

Choose a reason for hiding this comment

jquick Sep 27, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jerryaldrichiii left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jerryaldrichiii Sep 27, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jquick left a comment

Choose a reason for hiding this comment

clintoncwolfe commented Sep 27, 2018 •

edited

Loading

jquick Sep 27, 2018 •

edited

Loading

jerryaldrichiii Sep 27, 2018 •

edited

Loading