diff --git a/docs/hooks/go.rst b/docs/hooks/go.rst index f9e001921..03dc6b4c8 100644 --- a/docs/hooks/go.rst +++ b/docs/hooks/go.rst @@ -19,12 +19,15 @@ Installation Usage ----- -Using Dredd with Go is slightly different to other languages, as a binary needs to be compiled for execution. The –hookfiles flags should point to compiled hook binaries. See below for an example hooks.go file to get an idea of what the source file behind the go binary would look like. +Using Dredd with Go is slightly different to other languages, as a binary needs to be compiled for execution. The :option:`--hookfiles` options should point to compiled hook binaries. See below for an example hooks.go file to get an idea of what the source file behind the go binary would look like. :: $ dredd apiary.apib http://127.0.0.1:3000 --server=./go-lang-web-server-to-test --language=go --hookfiles=./hook-file-binary +.. note:: + If you're running :ref:`Dredd inside Docker `, read about :ref:`specifics of getting it working together with non-JavaScript hooks `. + API Reference ------------- diff --git a/docs/hooks/index.rst b/docs/hooks/index.rst index 8bd3b0e39..860f48681 100644 --- a/docs/hooks/index.rst +++ b/docs/hooks/index.rst @@ -94,7 +94,7 @@ Now the tests should pass even if publishing new article requires auth. Supported languages ------------------- -Dredd itself is written in JavaScript, so it supports :ref:`JavaScript hooks ` out of the box. Hook handlers for other languages need to be installed before they can be used. Supported languages are: +Dredd itself is written in JavaScript, so it supports :ref:`JavaScript hooks ` out of the box. Running hooks in other languages requires installing a dedicated *hook handler*. Supported languages are: .. toctree:: :maxdepth: 1 @@ -189,3 +189,18 @@ Hooks get executed at specific points in Dredd's :ref:`execution life cycle `, you may want to use a separate container for the hook handler and then run all your containers together as described in the :ref:`docker-compose` section. + +However, hooks were not originally designed with this scenario in mind. Dredd gets a name of (or path to) the hook handler in :option:`--language` and then starts it as a child process. To work around this, `fool Dredd with a dummy script `__ and set :option:`--hooks-worker-handler-host` together with :option:`--hooks-worker-handler-port` to point Dredd's TCP communication to the other container. + +.. note:: + The issue described above is tracked in :ghissue:`#755`. diff --git a/docs/hooks/perl.rst b/docs/hooks/perl.rst index 6b83ec3a8..e8ad58df5 100644 --- a/docs/hooks/perl.rst +++ b/docs/hooks/perl.rst @@ -23,6 +23,10 @@ Usage $ dredd apiary.apib http://127.0.0.1:3000 --language=dredd-hooks-perl --hookfiles=./hooks*.pl + +.. note:: + If you're running :ref:`Dredd inside Docker `, read about :ref:`specifics of getting it working together with non-JavaScript hooks `. + API Reference ------------- diff --git a/docs/hooks/php.rst b/docs/hooks/php.rst index bdf00dd9a..87d6e5de4 100644 --- a/docs/hooks/php.rst +++ b/docs/hooks/php.rst @@ -30,6 +30,9 @@ Usage $ dredd apiary.apib http://127.0.0.1:3000 --language=vendor/bin/dredd-hooks-php --hookfiles=./hooks*.php +.. note:: + If you're running :ref:`Dredd inside Docker `, read about :ref:`specifics of getting it working together with non-JavaScript hooks `. + API Reference ------------- diff --git a/docs/hooks/python.rst b/docs/hooks/python.rst index 0da625031..e1e784241 100644 --- a/docs/hooks/python.rst +++ b/docs/hooks/python.rst @@ -23,6 +23,9 @@ Usage $ dredd apiary.apib http://127.0.0.1:3000 --language=python --hookfiles=./hooks*.py +.. note:: + If you're running :ref:`Dredd inside Docker `, read about :ref:`specifics of getting it working together with non-JavaScript hooks `. + API Reference ------------- diff --git a/docs/hooks/ruby.rst b/docs/hooks/ruby.rst index 54a89d974..9e93c968d 100644 --- a/docs/hooks/ruby.rst +++ b/docs/hooks/ruby.rst @@ -23,6 +23,9 @@ Usage $ dredd apiary.apib http://127.0.0.1:3000 --language=ruby --hookfiles=./hooks*.rb +.. note:: + If you're running :ref:`Dredd inside Docker `, read about :ref:`specifics of getting it working together with non-JavaScript hooks `. + API Reference ------------- diff --git a/docs/hooks/rust.rst b/docs/hooks/rust.rst index 8f1594658..61ece558c 100644 --- a/docs/hooks/rust.rst +++ b/docs/hooks/rust.rst @@ -19,12 +19,15 @@ Installation Usage ----- -Using Dredd with Rust is slightly different to other languages, as a binary needs to be compiled for execution. The –hookfiles flags should point to compiled hook binaries. See below for an example hooks.rs file to get an idea of what the source file behind the Rust binary would look like. +Using Dredd with Rust is slightly different to other languages, as a binary needs to be compiled for execution. The :option:`--hookfiles` options should point to compiled hook binaries. See below for an example hooks.rs file to get an idea of what the source file behind the Rust binary would look like. :: $ dredd apiary.apib http://127.0.0.1:3000 --server=./rust-web-server-to-test --language=rust --hookfiles=./hook-file-binary +.. note:: + If you're running :ref:`Dredd inside Docker `, read about :ref:`specifics of getting it working together with non-JavaScript hooks `. + API Reference ------------- diff --git a/docs/installation.rst b/docs/installation.rst index dc13e4505..236e9bbfc 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -7,12 +7,16 @@ Installation There are several options how to run Dredd on your machine or in your :ref:`continuous-integration`. +.. _docker: .. _install-docker: Docker ------ -Installing Dredd using `Docker `__ is the easiest and the most hassle-free option for every major operating system. +If you are familiar with `Docker `__, you can get started with Dredd quickly by using the ready-made `apiaryio/dredd `__ image. Specifics of running Dredd inside Docker are: + +- you won't be able to use the :option:`--server` option (see :ref:`docker-compose`) +- setting up non-JavaScript :ref:`hooks ` is less straightforward (see :ref:`hooks-docker`) .. tabs:: @@ -37,18 +41,28 @@ Installing Dredd using `Docker `__ is the easiest and t C:\Users\Susan> docker run -it -v ${pwd}:/api -w /api apiaryio/dredd dredd init +.. _docker-compose: + +Docker Compose +~~~~~~~~~~~~~~ + +Inside Docker it's impossible for Dredd to manage child processes, so the :option:`--server` and :option:`--language` options won't work properly. + +Instead, you should have separate containers for each process and run them together with Dredd using `Docker Compose `__. You can `use -\\-abort-on-container-exit and -\\-exit-code-from `__ with Docker Compose to manage the tear down of all the other containers when the Dredd tests finish. + + .. _install-npm: npm --- -Dredd is a command-line application written in JavaScript, or to be more precise, in `Node.js `__. If Docker isn't an option for you, it's possible to install Dredd using the `npm `__. +Dredd is a command-line application written in JavaScript (to be more precise, in `Node.js `__) and as such can be installed using `npm `__. .. _install-nodejs: -Installing Node.js -~~~~~~~~~~~~~~~~~~ +Installing Node.js and npm +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tabs:: @@ -72,7 +86,7 @@ Installing Node.js - Make sure both ``node --version`` and ``npm --version`` work in your Command Prompt - Node.js needs to be at least version 6 -.. warning:: +.. note:: If your internet connection is restricted (VPN, firewall, proxy), you need to `configure npm `__: .. code-block:: text @@ -102,7 +116,7 @@ Now that you have everything prepared, you can finally run npm to install Dredd: npm install dredd --global -.. warning:: +.. note:: If you get ``EACCES`` permissions errors, try `one of the officially recommended solutions `__. In the worst case, you can run the command again with ``sudo``. You can verify Dredd is correctly installed by printing its version number: @@ -114,8 +128,8 @@ You can verify Dredd is correctly installed by printing its version number: Now you can :ref:`start using Dredd `! -Adding Dredd as dev dependency -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adding Dredd as a dev dependency +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your API project is also an npm package, you may want to add Dredd as a dev dependency instead of installing it globally.