Permalink
Browse files

add section on trigger testing to readme

  • Loading branch information...
1 parent 605f0b1 commit 776e67e721ec6545e73e0b11a26e5fd0557c7847 @hunterlang hunterlang committed Feb 15, 2013
Showing with 129 additions and 1 deletion.
  1. +129 −1 README.md
View
130 README.md
@@ -72,4 +72,132 @@ Getting Started
* For **Goodies** or **Spice**, proceed to the [Basic tutorial](https://github.com/duckduckgo/zeroclickinfo-goodies) in the Goodies repository.
* For **Fathead**, check out the Readme in the [fathead repository](https://github.com/duckduckgo/zeroclickinfo-fathead).
- * For **Longtail**, check out the Readme in the [longtail repository](https://github.com/duckduckgo/zeroclickinfo-longtail).
+ * For **Longtail**, check out the Readme in the [longtail repository](https://github.com/duckduckgo/zeroclickinfo-longtail).
+
+Advanced Stuff
+===
+
+## Testing Triggers
+### Pre-requisites:
+Before reading this section, make sure you've at least worked through the [basic tutorial](https://github.com/duckduckgo/zeroclickinfo-goodies/blob/master/README.md#basic-tutorial).
+
+
+----
+
+**Step 1.**  Install our DuckDuckHack utility called [duckpan](https://metacpan.org/module/duckpan):
+
+```bash
+curl http://duckpan.org/install.pl | perl
+```
+
+[This script](https://github.com/duckduckgo/p5-duckpan-installer) will setup [local::lib](https://metacpan.org/module/local::lib), which is a way to install Perl modules without changing your base Perl installation. (If you already use local::lib or [perlbrew](https://metacpan.org/module/perlbrew), don't worry, this script will intelligently use what you already have.)
+
+If you didn't have a local::lib before running the install script, you will need to run the script twice. It should tell you when like this:
+
+```txt
+please now re-login to your user account and run it again!
+```
+
+If everything works, you should see this at the end:
+
+```bash
+EVERYTHING OK! You can now go hacking! :)
+```
+
+Note that with local::lib now installed, you can easily install [Perl modules](http://search.cpan.org/) with [cpanm](https://metacpan.org/module/cpanm).
+
+```bash
+cpanm App::DuckPAN
+App::DuckPAN is up to date.
+```
+
+**Step 2.**  Go to your fork of the repository (a directory or folder on your computer).
+
+```bash
+cd zeroclickinfo-goodies/
+```
+
+**Step 3.**  Install the repository requirements using duckpan.
+
+```txt
+duckpan installdeps
+```
+
+This command will install all the Perl modules used by the DuckDuckGo plugins within your local repository. These requirements are defined in the [/dist.ini file](http://blog.urth.org/2010/06/walking-through-a-real-distini.html) (at the root).
+
+**Step 4.** Add your plugin.
+
+Make a new file in the **lib/DDG/Goodie/** directory for Goodies or the **lib/DDG/Spice/** directory for Spice. The name of the file is the name of the plugin followed by the extension **.pm** because it is a Perl package. For example, if the name of your plugin was _TestPlugin_, the file would be _TestPlugin.pm_.
+
+**Step 5.** Test your trigger(s) interactively.
+
+Type this command at the command line.
+
+```txt
+duckpan goodie test
+```
+
+First, this command will output all of the plugins available in your local plugin repository.
+
+```md
+Using the following DDG::Goodie plugins:
+
+ - DDG::Goodie::Xor (Words)
+ - DDG::Goodie::SigFigs (Words)
+ - DDG::Goodie::EmToPx (Words)
+ - DDG::Goodie::Length (Words)
+ - DDG::Goodie::ABC (Words)
+ - DDG::Goodie::Chars (Words)
+ ...
+```
+
+You should see your plugin in there as well. When the output is finished it gives you an interactive prompt.
+
+```
+(Empty query for ending test)
+Query:
+```
+
+Now you can type in any query and see what the response will be.
+
+```
+Query: chars this is a test
+
+DDG::ZeroClickInfo {
+ Parents WWW::DuckDuckGo::ZeroClickInfo
+ Linear @ISA DDG::ZeroClickInfo, WWW::DuckDuckGo::ZeroClickInfo, Moo::Object
+ public methods (3) : is_cached, new, ttl
+ private methods (0)
+ internals: {
+ answer 14,
+ answer_type "chars",
+ is_cached 1
+ }
+}
+```
+
+There is a lot of debugging output, but you will want to pay special attention to the internals section.
+
+```txt
+ internals: {
+ answer 14,
+ answer_type "chars",
+ is_cached 1
+ }
+```
+
+Here you can see the answer returned, as well as any **zci** keywords (by default there will be a default **answer_type** and **is_cached** value).
+
+Simply hit enter (a blank query) to exit interactive mode.
+
+```txt
+Query:
+
+\_o< Thanks for testing!
+```
+
+### Where to go now:
+
+* You may want to build a test file in the [Advanced trigger testing](#advanced-trigger-testing) section.
+* If you're making a **Goodie** plugin, you can go directly to the [Submitting plugins](#submitting-plugins) section.
+* If you're following along with the **Spice** plugin docs, you should go to the section on [Spice callback functions](https://github.com/duckduckgo/zeroclickinfo-spice/blob/master/README.md#spice-callback-functions).

0 comments on commit 776e67e

Please sign in to comment.