> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# ghostinspector/test-runner

Execute your Ghost Inspector browser tests and suites within your CircleCI build environment.


## Commands

### execute-test

Trigger your Ghost Inspector test from a CircleCI build, passing in the test `id`, optional
`extra-params` required for your test, and optional `start-url`. Your `api-key` will be
read from the environment variable `$GI_API_KEY` if set, or can be provided explicitly in
the `ghostinspector/execute-test` command with the `api-key` parameter. By specifying `wait`
as `true` the test runner will pass or fail your build with the status of your test.

It is recommended that you use the `ghostinspector/default` executor to run this command,
however if you wish to use a different executor, simply ensure that `curl` and `jq` are
installed and available on the `$PATH`.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-key` | string | $GI_API_KEY | Your Ghost Inspector API key. |
| `id` | string |  | ID of the Ghost Inspector test to execute. |
| `start-url` | string |  | (optional) Modify the start URL to execute your test against. |
| `extra-params` | string | {} | (optional) Extra parameters to POST to the execute endpoint, in JSON format, defaults to `{}`. |
| `wait` | boolean | false | (optional) Wait for the test execution to complete before proceeding, defaults to `false`. |

### execute-suite

Trigger your Ghost Inspector suite from a CircleCI build, passing in the suite `id`, optional
`extra-params` required for your suite, and optional `start-url`. Your `api-key` will be
read from the environment variable `$GI_API_KEY` if set, or can be provided explicitly in
the `ghostinspector/execute-suite` command with the `api-key` parameter. By specifying `wait`
as `true` the test runner will pass or fail your build with the status of your suite.

It is recommended that you use the `ghostinspector/default` executor to run this command,
however if you wish to use a different executor, simply ensure that `curl` and `jq` are
installed and available on the `$PATH`.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-key` | string | $GI_API_KEY | Your Ghost Inspector API key. |
| `id` | string |  | ID of the Ghost Inspector suite to execute. |
| `start-url` | string |  | (optional) Modify the start URL to execute your suite against. |
| `extra-params` | string | {} | (optional) Extra parameters to POST to the execute endpoint, in JSON format, defaults to `{}`. |
| `wait` | boolean | false | (optional) Wait for the suite execution to complete before proceeding, defaults to `false`. |

### test-standalone-app

Execute a Ghost Inspector test suite against a running application container by passing the
command the `vpn-target` of your running application. Specify the Ghost Inspector `suite-id`
you wish to run against your application and provide any `extra-params` as a JSON string to
pass into your test suite at run time.  Your `api-key` will be read from the environment
variable `$GI_API_KEY` if set, or can be provided explicitly in the
`ghostinspector/test-standalone-app` command with the `api-key` parameter.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-key` | string | $GI_API_KEY | Your Ghost Inspector API key. |
| `suite-id` | string |  | The ID of the Ghost Inspector test suite to execute. |
| `extra-params` | string | {} | (optional) Extra parameters to POST to the execute endpoint, in JSON format, defaults to `{}`. |
| `vpn-token` | string | $GI_VPN_TOKEN | Your ngrok API key. |
| `vpn-target` | string |  | A combination of the container hostname (from the `--name` argument used to start the
container) and port on your docker container where the application under test may be
reached, example `my-app:8000`.
 |
| `network` | string |  | The name of the docker network (from the `--network` argument used to start the container)
attached to your running application container.
 |

## Executors

### default

## Examples

### execute-ghost-inspector-test

Same Ghost Inspector test execution.

```yaml
version: 2.1
orbs:
  ghostinspector: ghostinspector/test-runner@1.0.2
jobs:
  build:
    executor: ghostinspector/default
    steps:
      - ghostinspector/execute-test:
          id: <my-test-id>
          extra-params: '{"foo": "bar", "other": "var"}'
          wait: true
```

### execute-ghost-inspector-suite

Sample Ghost Inspector suite execution.

```yaml
version: 2.1
orbs:
  ghostinspector: ghostinspector/test-runner@1.0.2
jobs:
  build:
    executor: default
    steps:
      - ghostinspector/execute-suite:
          id: <my-suite-id>
          extra-params: '{"myVar": "foo", "otherVar": "bar"}'
          wait: true
```

### test-standalone-app

Execute a Ghost Inspector test suite against a your dockerized application container.

```yaml
version: 2.1
orbs:
  ghostinspector: ghostinspector/test-runner@1.0.2
executors:
  docker-executor:
    docker:
      - image: docker:17.05.0-ce-git
jobs:
  build_and_test:
    executor: docker-executor
    steps:
      - setup_remote_docker
      - run:
          name: Set up temporary docker network
          command: docker network create my-docker-network
      - run:
          name: >-
            Start your application container, specifying application port and
            docker network
          command: |
            docker run -d \
              -e PORT=8080 \
              --network my-docker-network \
              --name my-app \
              my-docker-image
      - ghostinspector/test-docker-app:
          api-key: <my-ghost-inspector-api-key>
          suite-id: <my-ghost-inspector-suite-id>
          network: my-docker-network
          vpn-token: <my-ngrok-token>
          vpn-target: my-docker-image:8080
```