### Install Venom from Binaries (Linux)

Source: https://github.com/ovh/venom/blob/master/README.md

Installs the latest Venom binary for Linux and provides a command to check the help output.

```bash
$ curl https://github.com/ovh/venom/releases/download/v1.2.0/venom.linux-amd64 -L -o /usr/local/bin/venom && chmod +x /usr/local/bin/venom
$ venom -h
```

--------------------------------

### HTTP GET Request Example

Source: https://github.com/ovh/venom/blob/master/executors/http/README.md

Demonstrates a basic HTTP GET request to an API endpoint. Includes assertions to check for specific substrings in the response body and verify the status code.

```yaml
name: HTTP testsuite
testcases:
- name: get http testcase
  steps:
  - type: http
    method: GET
    url: https://eu.api.ovh.com/1.0/
    assertions:
    - result.body ShouldContainSubstring /dedicated/server
    - result.body ShouldContainSubstring /ipLoadbalancing
    - result.statuscode ShouldEqual 200
    - result.bodyjson.api ShouldBeNil
    - result.bodyjson.apis ShouldNotBeEmpty
    - result.bodyjson.apis.apis0 ShouldNotBeNil
    - result.bodyjson.apis.apis0.path ShouldEqual /allDom
```

--------------------------------

### Couchbase Entry Example

Source: https://github.com/ovh/venom/blob/master/executors/couchbase/README.md

An example of how to define a Couchbase entry with its ID and content.

```yaml
airline_01: # entries are specified as map id => content
  "id": 1
  "type": "airline"
  "name": "first airline"
  "country": "Latveria"
```

--------------------------------

### Web Test Case Example

Source: https://github.com/ovh/venom/blob/master/executors/web/README.md

A comprehensive example demonstrating a full web test case. It includes setting up browser variables, navigating to a URL, finding elements, filling input fields, clicking buttons, and taking a screenshot.

```yaml
name: TestSuite Web
vars:
  web:
    driver: chrome
    width: 1920
    height: 1080
    args:
    - 'browser-test'
    prefs:
      profile.default_content_settings.popups: 0
      profile.default_content_setting_values.notifications: 1
    timeout: 60
    debug: true
testcases:
- name: TestCase Google search
  steps:
  - type: web
    action:
      navigate:
        url: https://www.google.fr
    assertions:
    - result.title ShouldEqual Google
    - result.url ShouldEqual https://www.google.fr
  - type: web
    action:
      find: input[name="q"]
    assertions:
     - result.find ShouldEqual 1
  - type: web
    action:
      fill:
      - find: input[name="q"]
        text: "venom ovh"
  - type: web
    action:
      click:
        find: input[value="Recherche Google"]
        wait: 1
    screenshot: googlesearch.png

```

--------------------------------

### Read File Example with Assertions

Source: https://github.com/ovh/venom/blob/master/executors/readfile/README.md

An example Venom test file demonstrating reading different file types (JSON, text) and asserting their content.

```yaml
name: TestSuite Read File
testcases:
- name: TestCase Read File
  steps:
  - type: readfile
    path: testa.json
    assertions:
      - result.contentjson.foo ShouldEqual bar

  - type: readfile
    path: testb.json
    assertions:
      - result.contentjson.contentjson0.foo2 ShouldEqual bar2

  - type: readfile
    path: testa.txt
    assertions:
      - result.content ShouldContainSubstring multilines
```

--------------------------------

### Run Integration Tests

Source: https://github.com/ovh/venom/blob/master/README.md

Command to execute the integration tests after setup.

```bash
make run-test
```

--------------------------------

### Prepare Integration Test Environment

Source: https://github.com/ovh/venom/blob/master/README.md

Steps to build Venom for Linux/AMD64, copy it to the test directory, and start the test stack.

```bash
make build OS=linux ARCH=amd64
cp dist/venom.linux-amd64 tests/venom
cd tests
make start-test-stack  # (wait a few seconds)
make build-test-binary-docker
```

--------------------------------

### Venom Update Process Example

Source: https://github.com/ovh/venom/blob/master/README.md

Illustrates the output and process when the `venom update` command is executed, showing the download and completion.

```bash
Url to update venom: https://github.com/ovh/venom/releases/download/v1.2.0/venom.darwin-amd64
Getting latest release from: https://github.com/ovh/venom/releases/download/v1.2.0/venom.darwin-amd64 ...
Update done.
```

--------------------------------

### Example Custom Executor Implementation

Source: https://github.com/ovh/venom/blob/master/executors/README.md

A complete Go example of a custom Venom executor. This includes defining the executor, its result structure, default assertions, and the Run method logic.

```go
// Name of executor
const Name = "myexecutor"

// New returns a new Executor
func New() venom.Executor {
	return &Executor{}
}

// Executor struct
type Executor struct {
	Command string `json:"command,omitempty" yaml:"command,omitempty"
}

// Result represents a step result
type Result struct {
	Code        int    `json:"code,omitempty" yaml:"code,omitempty"
	Command     string `json:"command,omitempty" yaml:"command,omitempty"
	Systemout   string   `json:"systemout,omitempty" yaml:"systemout,omitempty" // put in testcase.Systemout by venom if present
	Systemerr   string   `json:"systemerr,omitempty" yaml:"systemerr,omitempty" // put in testcase.Systemerr by venom if present
}

// GetDefaultAssertions returns the default assertions for this executor
// Optional
func (Executor) GetDefaultAssertions() *venom.StepAssertions {
	return &venom.StepAssertions{Assertions: []venom.Assertion{"result.code ShouldEqual 0"}}
}

// Run executes TestStep
func (Executor) Run(ctx context.Context, step venom.TestStep) (interface{}, error) {
	// transform step to Executor Instance
	var e Executor
	if err := mapstructure.Decode(step, &e); err != nil {
		return nil, err
	}

	// to something with e.Command here...
	//...

	systemout := "foo"
	outputCode := 0

	// prepare result
	r := Result{
		Code:    outputCode, // return Output Code
		Command: e.Command, // return Command executed
		Systemout: systemout, // return Output string
	}

	return r, nil
}

```

--------------------------------

### Venom Configuration File Example

Source: https://github.com/ovh/venom/blob/master/README.md

Defines Venom settings such as variables, output directories, and verbosity. Command-line flags override these settings.

```yaml
variables: 
- foo=bar
variables_files:
- my_var_file.yaml
stop_on_failure: true
format: xml
output_dir: output
lib_dir: lib
verbosity: 3
```

--------------------------------

### AMQP Producer Example

Source: https://github.com/ovh/venom/blob/master/executors/amqp/README.md

Example of configuring the AMQP executor as a producer to publish messages to a specified address and target topic/queue. Supports publishing JSON and plain text messages.

```yaml
name: AMQP
testcases:
  - name: Producer
    steps:
      - type: amqp
        addr: amqp://localhost:5673
        clientType: producer
        targetAddr: amqp-test
        messages:
          - '{"key1":"value1","key2":"value2"}'
          - '{"key3":"value3","key4":"value4"}'
          - 'not json'
          - '["value5","value6"]'
```

--------------------------------

### AMQP Consumer Example

Source: https://github.com/ovh/venom/blob/master/executors/amqp/README.md

Example of configuring the AMQP executor as a consumer to subscribe to messages from a specified source address. It demonstrates setting a message limit and includes assertions to verify received messages and their JSON parsed bodies.

```yaml
name: AMQP
testcases:
  - name: Consumer
    steps:
     - type: amqp
        addr: amqp://localhost:5673
        clientType: consumer
        sourceAddr: amqp-test
        messageLimit: 4
        assertions:
          - result.messages.__Len__ ShouldEqual 4
          - result.messages.messages0 ShouldEqual '{"key1":"value1","key2":"value2"}'
          - result.messages.messages1 ShouldEqual '{"key3":"value3","key4":"value4"}'
          - result.messages.messages2 ShouldEqual 'not json'
          - result.messages.messages3 ShouldEqual '["value5","value6"]'
          - result.messagesjson.__Len__ ShouldEqual 4
          - result.messagesjson.messagesjson0.key1 ShouldEqual value1
          - result.messagesjson.messagesjson0.key2 ShouldEqual value2
          - result.messagesjson.messagesjson1.key3 ShouldEqual value3
          - result.messagesjson.messagesjson1.key4 ShouldEqual value4
          - result.messagesjson.messagesjson3.messagesjson30 ShouldEqual value5
          - result.messagesjson.messagesjson3.messagesjson31 ShouldEqual value6
```

--------------------------------

### Basic Read File Step

Source: https://github.com/ovh/venom/blob/master/executors/readfile/README.md

A simple example of a read file step in a Venom test suite, checking for errors.

```yaml
name: TestSuite Read File
testcases:
- name: TestCase Read File
  steps:
  - type: readfile
    path: yourfile.txt
    assertions:
    - result.err ShouldBeEmpty
```

--------------------------------

### Testa.json File Content

Source: https://github.com/ovh/venom/blob/master/executors/readfile/README.md

Example content for a JSON file.

```json
{
  "foo": "bar"
}
```

--------------------------------

### Run Venom with Custom Executors

Source: https://github.com/ovh/venom/blob/master/README.md

Command-line examples for running Venom tests. The first command loads executors from the default 'lib/' directory. The second command specifies multiple custom library directories.

```bash
# lib/*.yml files will be loaded as executors.
$ venom run testsuite.yml 
```

```bash
# executors will be loaded from /etc/venom/lib, $HOME/venom.d/lib and lib/ directory relative to testsuite.yml file.
$ venom run --lib-dir=/etc/venom/lib:$HOME/venom.d/lib testsuite.yml 
```

--------------------------------

### RabbitMQ Subscriber (Pub/Sub)

Source: https://github.com/ovh/venom/blob/master/executors/rabbitmq/README.md

Configure a subscriber to consume messages from an exchange using a specific routing key in a publish/subscribe setup. This example includes assertions to verify the received message content and headers.

```yaml
name: TestSuite RabbitMQ
vars:
  addrs: 'amqp://localhost:5672'
  user: 
  password: 
  - name: RabbitMQ subscribe testcase
    steps:
      - type: rabbitmq
        addrs: "{{.addrs}}"
        user: "{{.user}}"
        password: "{{.password}}"
        clientType: subscriber
        exchange: exchange_test
        routingKey: pubsub_test
        messageLimit: 1
        assertions: 
          - result.bodyjson.bodyjson0.a ShouldEqual b   
          - result.headers.headers0.mycustomheader ShouldEqual value
          - result.headers.headers0.mycustomheader2 ShouldEqual value2
          - result.messages.messages0.contentencoding ShouldEqual utf8
          - result.messages.messages0.contenttype ShouldEqual application/json
```

--------------------------------

### Testa.txt File Content

Source: https://github.com/ovh/venom/blob/master/executors/readfile/README.md

Example content for a simple text file.

```text
simple content
multilines
```

--------------------------------

### OVH API TestSuite using App Keys Authentication

Source: https://github.com/ovh/venom/blob/master/executors/ovhapi/README.md

Example of a Venom test suite making a GET request to the /me endpoint using App Keys authentication. Includes assertions for status code and response body content.

```yaml
name: Title of TestSuite
testcases:
- name: me
  steps:
  - type: ovhapi
    endpoint: 'ovh-eu'
    applicationKey: 'APPLICATION_KEY'
    applicationSecret: 'APPLICATION_SECRET'
    consumerKey: 'CONSUMER_KEY'
    method: GET
    path: /me
    retry: 3
    delay: 2
    assertions:
    - result.statuscode ShouldEqual 200
    - result.bodyjson.nichandle ShouldContainSubstring MY_NICHANDLE
```

--------------------------------

### Redis Commands Example

Source: https://github.com/ovh/venom/blob/master/executors/redis/README.md

Execute a series of Redis commands directly within a step. Assertions can be made against the responses.

```yaml
name: Redis testsuite
vars: 
  redis.dialURL: "redis://localhost:6379/0"
  
testcases:
- name: test-commands
  steps:
  - type: redis
    commands:
        - FLUSHALL
  - type: redis
    commands:
        - SET foo bar
        - GET foo
        - KEYS *
    assertions:
        - result.commands.commands0.response ShouldEqual OK
        - result.commands.commands1.response ShouldEqual bar
        - result.commands.commands2.response.response0 ShouldEqual foo
  - type: redis
    commands:
        - KEYS *
    assertions:
        - result.commands.commands0.response.response0 ShouldEqual foo
```

--------------------------------

### Compile ODBC Executor on macOS

Source: https://github.com/ovh/venom/blob/master/executors/plugins/odbc/README.md

Example command for compiling the ODBC executor on macOS, specifying CGO flags for a Homebrew-installed ODBC driver.

```bash
$ CGO_CFLAGS="-I$HOME/homebrew/Cellar/unixodbc/2.3.9/include" CGO_LDFLAGS="-L$HOME/homebrew/lib" go build
```

--------------------------------

### Testb.json File Content

Source: https://github.com/ovh/venom/blob/master/executors/readfile/README.md

Example content for a JSON file containing an array of objects.

```json
[
  {
    "foo": "bar",
    "foo2": "bar2"
  }

]
```

--------------------------------

### Basic gRPC Request Example

Source: https://github.com/ovh/venom/blob/master/executors/grpc/README.md

Demonstrates a basic gRPC request with URL, service, method, and data. Assertions check the gRPC status code and a field in the JSON output.

```yaml
name: Title of TestSuite
testcases:

- name: request GRPC
  steps:
  - type: grpc
    url: serverUrlWithoutHttp:8090
    data:
      foo: bar
    service: coolService.api
    method: GetAllFoos
    assertions:
    - result.code ShouldEqual 0
    - result.systemoutjson.foo ShouldEqual bar
```

--------------------------------

### Display Help for Venom Run Command

Source: https://github.com/ovh/venom/blob/master/README.md

Shows the help information specific to the `venom run` command, detailing its flags and examples.

```bash
$ venom run -h

run integration tests

Usage:
  venom run [flags]

Examples:
  Run all testsuites containing in files ending with *.yml or *.yaml: venom run
  Run a single testsuite: venom run mytestfile.yml
  Run a single testsuite and export the result in JSON format in test/ folder: venom run mytestfile.yml --format=json --output-dir=test
  Run a single testsuite and export the result in XML and HTML formats in test/ folder: venom run mytestfile.yml --format=xml --output-dir=test --html-report
  Run a single testsuite and specify a variable: venom run mytestfile.yml --var="foo=bar"
  Run a single testsuite and load all variables from a file: venom run mytestfile.yml --var-from-file variables.yaml
  Run all testsuites containing in files ending with *.yml or *.yaml with verbosity: VENOM_VERBOSE=2 venom run

  Notice that variables initialized with -var-from-file argument can be overrided with -var argument

  More info: https://github.com/ovh/venom

Flags:
      --format string           --format:json, tap, xml, yaml (default "xml")
  -h, --help                    help for run
      --html-report             Generate HTML Report
      --lib-dir string          Lib Directory: can contain user executors. example:/etc/venom/lib:$HOME/venom.d/lib
      --output-dir string       Output Directory: create tests results file inside this directory
      --stop-on-failure         Stop running Test Suite on first Test Case failure
      --var stringArray         --var cds='cds -f config.json' --var cds2='cds -f config.json'
      --var-from-file strings   --var-from-file filename.yaml --var-from-file filename2.yaml: yaml, must contains a dictionary
  -v, --verbose count           verbose. -v (INFO level in venom.log file), -vv to very verbose (DEBUG level) and -vvv to very verbose with CPU Profiling

```

--------------------------------

### Kafka Producer and Consumer Example (No Avro)

Source: https://github.com/ovh/venom/blob/master/executors/kafka/README.md

Demonstrates a Kafka producer sending a JSON message and a consumer reading it. Ensure TLS and SASL are configured if required by your Kafka cluster.

```yaml
name: My Kafka testsuite
version: "2"
testcases:
- name: Kafka test
  description: Test Kafka
  steps:
  - type: kafka
    clientType: producer
    withSASL: true
    withTLS: true
    user: "{{.kafkaUser}}"
    password: "{{.kafkaPwd}}"
    addrs:
      - "{{.kafkaHost}}:{{.kafkaPort}}"
    messages:
    - topic: test-topic
      value: '{"hello":"bar"}'
  - type: kafka
    clientType: consumer
    withTLS: true
    withSASL: true
    user: "{{.kafkaUser}}"
    password: "{{.kafkaPwd}}"
    markOffset: true
    initialOffset: oldest
    messageLimit: 1
    groupID: venom
    addrs:
      - "{{.kafkaHost}}:{{.kafkaPort}}"
    topics:
      - test-topic
    assertions:
    - result.messagesjson.messagesjson0.value.hello ShouldEqual bar
    - result.messages.__Len__ ShouldEqual 1

```

--------------------------------

### Kafka Producer and Consumer Example (With Avro)

Source: https://github.com/ovh/venom/blob/master/executors/kafka/README.md

Illustrates using Avro schemas for producing and consuming messages. The producer specifies value and schema files, while the consumer asserts Avro-decoded message content. Ensure Avro schema files are correctly referenced.

```yaml
name: My Kafka testsuite
version: "2"
testcases:
- name: Kafka test
  description: Test Kafka
  steps:
  - type: kafka
    clientType: producer
    withSASL: true
    withTLS: true
    user: "{{.kafkaUser}}"
    password: "{{.kafkaPwd}}"
    addrs:
      - "{{.kafkaHost}}:{{.kafkaPort}}"
    messages:
    - topic: test-topic
      valueFile: "kafka/values/message2.json"
      avroSchemaFile: "kafka/schemas/message.avsc"
    - topic: test-topic
      valueFile: "kafka/values/message3.json"
  - type: kafka
    clientType: consumer
    withTLS: true
    withSASL: true
    user: "{{.kafkaUser}}"
    password: "{{.kafkaPwd}}"
    markOffset: true
    initialOffset: oldest
    messageLimit: 2
    groupID: venom
    addrs:
      - "{{.kafkaHost}}:{{.kafkaPort}}"
    topics:
      - test-topic
    assertions:
    - result.messagesjson.messagesjson0.value.id ShouldEqual 1
    - result.messagesjson.messagesjson0.value.message ShouldEqual "Some test"
    - result.messagesjson.messagesjson1.value.id ShouldEqual 2
    - result.messages.__Len__ ShouldEqual 2

```

--------------------------------

### Redis Commands from File Example

Source: https://github.com/ovh/venom/blob/master/executors/redis/README.md

Execute Redis commands stored in a file. The `path` parameter specifies the file, and `dialURL` can be overridden at the step level.

```yaml
- name: test-commands-from-file
  steps:
  - type: redis
    path: testredis/commands.txt
    dialURL: "redis://localhost:6379/0" # The global dialURL is overridden by this setting
    assertions:
        - result.commands.commands0.response ShouldEqual OK
        - result.commands.commands1.response ShouldEqual bar
        - result.commands.commands2.response.response0 ShouldEqual foo
```

--------------------------------

### Go Executor Plugin Example

Source: https://github.com/ovh/venom/blob/master/executors/plugins/README.md

Defines a custom 'hello' executor plugin in Go. It implements the venom.Executor interface and handles a simple 'arg' parameter to return a greeting. Requires mapstructure for decoding step arguments.

```go
package main

import (
	"C"
	"context"
	"fmt"

	"github.com/mitchellh/mapstructure"

	"github.com/ovh/venom"
)

// Name of the executor
const Name = "hello"

// Plugin var is mandatory, it's used by venom to register the executor
var Plugin = Executor{}

// Executor is a venom executor for Hello plugin
type Executor struct {
	Arg string `json:"arg,omitempty" yaml:"arg,omitempty"`
}

// Result represents a step result.
type Result struct {
	Body string `json:"body,omitempty" yaml:"body,omitempty"`
}

// Run implements the venom.Executor interface for Executor.
func (e Executor) Run(ctx context.Context, step venom.TestStep) (interface{}, error) {
	// Transform step to Executor instance.
	if err := mapstructure.Decode(step, &e); err != nil {
		return nil, err
	}

	venom.Debug(ctx, "running plugin Hello with arg %v\n", e.Arg)
	r := Result{Body: fmt.Sprintf("Hello %v", e.Arg)}
	return r, nil
}

// ZeroValueResult return an empty implementation of this executor result
func (e Executor) ZeroValueResult() interface{} {
	return Result{}
}

// GetDefaultAssertions return the default assertions of the executor.
func (e Executor) GetDefaultAssertions() venom.StepAssertions {
	return venom.StepAssertions{Assertions: []venom.Assertion{}}
}

```

--------------------------------

### OVH API TestSuite using OAuth2 Authentication

Source: https://github.com/ovh/venom/blob/master/executors/ovhapi/README.md

Example of a Venom test suite making a GET request to the /me endpoint using OAuth2 authentication. Includes assertions for status code and response body content.

```yaml
name: Title of TestSuite
testcases:
- name: me
  steps:
  - type: ovhapi
    endpoint: 'ovh-eu'
    clientID: 'CLIENT_ID'
    clientSecret: 'CLIENT_SECRET'
    method: GET
    path: /me
    retry: 3
    delay: 2
    assertions:
    - result.statuscode ShouldEqual 200
    - result.bodyjson.nichandle ShouldContainSubstring MY_NICHANDLE
```

--------------------------------

### Define a Custom Executor

Source: https://github.com/ovh/venom/blob/master/README.md

Define a custom executor named 'hello' with input arguments and steps. This example shows how to use the 'exec' script type and define output variables.

```yaml
executor: hello
input:
  myarg: {}
steps:
- script: echo "{"hello":"{{.input.myarg}}"}"
  assertions:
  - result.code ShouldEqual 0
vars:
  hello:
    from: result.systemoutjson.hello
  all:
    from: result.systemoutjson
output:
  display:
    hello: "{{.hello}}"
  all: "{{.all}}"
```

--------------------------------

### Venom TestSuite Structure Example

Source: https://github.com/ovh/venom/blob/master/README.md

Illustrates the YAML structure for defining a TestSuite, including test cases, steps, script execution, HTTP requests, and assertions.

```yaml
name: Title of TestSuite
description: A detailed description of the TestSuite, in markdown.
testcases:
- name: TestCase with default value, exec cmd. Check if exit code != 1
  steps:
  - script: echo 'foo'
    type: exec

- name: Title of First TestCase
  steps:
  - script: echo 'foo'
    assertions:
    - result.code ShouldEqual 0
  - script: echo 'bar'
    assertions:
    - result.systemout ShouldNotContainSubstring foo
    - result.timeseconds ShouldBeLessThan 1

- name: GET http testcase, with 5 seconds timeout
  steps:
  - type: http
    method: GET
    url: https://eu.api.ovh.com/1.0/
    timeout: 5
    assertions:
    - result.body ShouldContainSubstring /dedicated/server
    - result.body ShouldContainSubstring /ipLoadbalancing
    - result.statuscode ShouldEqual 200
    - result.timeseconds ShouldBeLessThan 1

- name: Test with retries and delay in seconds between each try
  steps:
  - type: http
    method: GET
    url: https://eu.api.ovh.com/1.0/
    retry: 3
    retry_if: # (optional, lets you early break unrecoverable errors)
    - result.statuscode ShouldNotEqual 403
    delay: 2
    assertions:
    - result.statuscode ShouldEqual 200
```

--------------------------------

### Basic SSH Command Execution

Source: https://github.com/ovh/venom/blob/master/executors/ssh/README.md

Example of a basic SSH step that checks the exit code and execution time of a simple 'echo' command.

```yaml
name: Title of TestSuite
testcases:
- name: Check if exit code != 1 and echo command response in less than 1s
  steps:
  - type: ssh
    host: localhost:2222
    command: echo 'foo'
    assertions:
    - result.code ShouldEqual 0
    - result.timeseconds ShouldBeLessThan 1
```

--------------------------------

### RabbitMQ Client (Pub/Sub RPC)

Source: https://github.com/ovh/venom/blob/master/executors/rabbitmq/README.md

Configure a client to send a request and wait for a reply, implementing a request/reply pattern over RabbitMQ. This example sends a JSON message and asserts the response status.

```yaml
name: TestSuite RabbitMQ
vars:
  addrs: 'amqp://localhost:5672'
  user: 
  password: 
testcases:
  - name: RabbitMQ request/reply
    steps:
      - type: rabbitmq
        addrs: "{{.addrs}}"
        user: "{{.user}}"
        password: "{{.password}}"
        clientType: client
        exchange: exchange_test
        routingKey: pubsub_test
        messages: 
          - value: '{"a": "b"}'
            contentType: application/json
            contentEncoding: utf8
            persistent: false
            headers: 
              myCustomHeader: value
              myCustomHeader2: value2
        messageLimit: 1
        assertions: 
          - result.bodyjson.bodyjson0 ShouldContainKey Status
          - result.bodyjson.bodyjson0.Status ShouldEqual Succeeded
```

--------------------------------

### Check Venom Version

Source: https://github.com/ovh/venom/blob/master/README.md

Checks the currently installed Venom version using the `venom version` command.

```bash
$ venom version
Version venom: v1.2.0 
```

--------------------------------

### Keys with similar prefixes

Source: https://github.com/ovh/venom/blob/master/variable_helpers.md

Ensures correct variable substitution when keys share common starting characters. Each key is resolved independently.

```go-template
a {{.myvar.myKey}} and another key value {{.myvar.myKeyAnother}}
```

--------------------------------

### IMAP Testsuite Example

Source: https://github.com/ovh/venom/blob/master/executors/imap/README.md

This YAML configuration defines an IMAP testsuite. It sets up connection variables and a test case to clear a mailbox, asserting that the command execution results in no errors.

```yaml
name: IMAP testsuite
vars:
  withTLS: false
  host: localhost
  port: 1143
  user: address@example.org
  password: pass
testcases:
  - name: Clear a mailbox
    steps:
      - type: imap
        auth:
          host: "{{.host}}"
          port: "{{.port}}"
          user: "{{.user}}"
          password: "{{.password}}"
        commands:
          - name: clear
            args:
              mailboxes:
                - INBOX
        assertions:
          # As multiple commands can be executed in a single testcase, we need to specify which command result we want to assert
          - result.commands.commands0.err ShouldBeEmpty

```

--------------------------------

### Use a Custom Executor in a Test Suite

Source: https://github.com/ovh/venom/blob/master/README.md

Use the custom 'hello' executor defined previously within a Venom test suite. This example demonstrates passing an argument to the executor and asserting on its output.

```yaml
name: testsuite with a user executor
testcases:
- name: testA
  steps:
  - type: hello
    myarg: World
    assertions:
    - result.display.hello ShouldContainSubstring World
    - result.alljson.hello ShouldContainSubstring World
```

--------------------------------

### RabbitMQ Publisher (Work Queue)

Source: https://github.com/ovh/venom/blob/master/executors/rabbitmq/README.md

Configure a publisher to send messages to a specific queue. Ensure the queue exists or is configured to be created. This example sends a JSON message with custom headers and encoding.

```yaml
name: TestSuite RabbitMQ
vars:
  addrs: 'amqp://localhost:5672'
  user: 
  password: 
testcases:
  - name: RabbitMQ publish (work Q)
    steps:
      - type: rabbitmq
        addrs: "{{.addrs}}"
        user: "{{.user}}"
        password: "{{.password}}"
        clientType: publisher
        qName: TEST
        messages: 
          - value: '{"a": "b"}'
            contentType: application/json
            contentEncoding: utf8
            persistent: false
            headers: 
              myCustomHeader: value
              myCustomHeader2: value2
```

--------------------------------

### Define API Integration Test Suite

Source: https://github.com/ovh/venom/blob/master/README.md

Create a test suite in a YAML file to define API integration tests. This example sets up a test for a public REST API, checking for a 200 status code, a response time under 5 seconds, and valid JSON content.

```yaml
name: APIIntegrationTest

vars:
  url: https://eu.api.ovh.com

testcases:
- name: GET http testcase, with 5 seconds timeout
  steps:
  - type: http
    method: GET
    url: {{.url}}/1.0/
    timeout: 5
    assertions:
    - result.statuscode ShouldEqual 200
    - result.timeseconds ShouldBeLessThan 1
    - result.bodyjson ShouldContainKey apis
    - result.body ShouldContainSubstring /dedicated/server
    - result.body ShouldContainSubstring /ipLoadbalancing
```

--------------------------------

### RabbitMQ Publisher (Pub/Sub)

Source: https://github.com/ovh/venom/blob/master/executors/rabbitmq/README.md

Configure a publisher to send messages to an exchange using a specific routing key for a publish/subscribe pattern. This example sends a JSON message with custom headers and encoding.

```yaml
name: TestSuite RabbitMQ
vars:
  addrs: 'amqp://localhost:5672'
  user: 
  password: 
testcases:
  - name: RabbitMQ publish (work Q)
    steps:
      - type: rabbitmq
        addrs: "{{.addrs}}"
        user: "{{.user}}"
        password: "{{.password}}"
        clientType: publisher
        exchange: exchange_test
        routingKey: pubsub_test
        messages: 
          - value: '{"a": "b"}'
            contentType: application/json
            contentEncoding: utf8
            persistent: false
            headers: 
              myCustomHeader: value
              myCustomHeader2: value2
```

--------------------------------

### Venom Test Suite Definition

Source: https://github.com/ovh/venom/blob/master/executors/plugins/README.md

Example of a Venom test suite YAML file defining a test case that uses the custom 'hello' executor plugin with an 'arg' parameter and an assertion on the result.

```yaml
name: TestSuite
testcases:
- name: TestAssertions
  steps:
  - type: hello
    arg: world
    assertions:
    - result.body ShouldContainSubstring world

```

--------------------------------

### gRPC Request with TLS Example

Source: https://github.com/ovh/venom/blob/master/executors/grpc/README.md

Shows how to configure TLS for a gRPC request, including root CA and ignoring SSL verification for self-signed certificates. Assertions check the gRPC status code and a field in the JSON output.

```yaml
name: Title of TestSuite
testcases:

- name: request GRPC
  steps:
  - type: grpc
    url: serverUrlWithoutHttp:8090
    tls_root_ca: |-
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    ignore_verify_ssl: true # true for self signed certificates
    data:
      foo: bar
    service: coolService.api
    method: GetAllFoos
    assertions:
    - result.code ShouldEqual 0
    - result.systemoutjson.foo ShouldEqual bar
```

--------------------------------

### Assertion Examples for IMAP Commands

Source: https://github.com/ovh/venom/blob/master/executors/imap/README.md

This YAML demonstrates how to assert the results of multiple IMAP commands within a single test case, covering command errors, mail search criteria, and mail states after execution.

```yaml
assertions:
  # First command
  - result.commands.commands0.err ShouldBeEmpty
  # State of the mail before command execution (search)
  - result.commands.commands0.search.from ShouldEqual "from@mail-before-command-execution.com"
  # Mail as a result of command execution
  - result.commands.commands0.mail.from ShouldEqual "to@mail-after-command-execution.com"
  # Second command
  - result.commands.commands1.err ShouldBeEmpty
  - result.commands.commands1.search.from ShouldEqual ...
  - result.commands.commands1.mail.from ShouldEqual ...
  - result.commands.commands1.mail.flags.flags0 ShouldEqual ...
  - result.commands.commands1.mail.flags.flags1 ShouldEqual ...
```

--------------------------------

### HTTP POST Request with Enhanced Assertions

Source: https://github.com/ovh/venom/blob/master/executors/http/README.md

A POST request example focusing on comprehensive assertions against the JSON response. It checks the response type, length, presence of specific keys, absence of others, and compares the status code against a variable.

```yaml
name: HTTP testsuite
testcases:
- name: post http enhanced assertions
  steps:
  - type: http
    method: POST
    url: https://eu.api.ovh.com/1.0/newAccount/rules
    assertions:
      - result.statuscode ShouldEqual 200
      - result.bodyjson.__Type__ ShouldEqual Array
      # Ensure a minimum of fields are present.
      - result.bodyjson.__Len__ ShouldBeGreaterThanOrEqualTo 8
      # Ensure fields have the right keys.
      - result.bodyjson.bodyjson0 ShouldContainKey fieldName
      - result.bodyjson.bodyjson0 ShouldContainKey mandatory
      - result.bodyjson.bodyjson0 ShouldContainKey regularExpression
      - result.bodyjson.bodyjson0 ShouldContainKey prefix
      - result.bodyjson.bodyjson0 ShouldContainKey examples
      - result.bodyjson.bodyjson0 ShouldNotContainKey lol
      - result.statuscode ShouldNotEqual {{.post-http-multipart.statuscode}}
```

--------------------------------

### gRPC Request with Mutual TLS Example

Source: https://github.com/ovh/venom/blob/master/executors/grpc/README.md

Illustrates configuring mutual TLS for a gRPC request, including client certificate and key, alongside root CA and ignoring SSL verification. Assertions check the gRPC status code and a field in the JSON output.

```yaml
name: Title of TestSuite
testcases:

- name: request GRPC
  steps:
  - type: grpc
    url: serverUrlWithoutHttp:8090
    tls_root_ca: |-
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    tls_client_cert: |-
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    tls_client_key: |-
      -----BEGIN PRIVATE KEY-----
      ...
      -----END PRIVATE KEY-----
    ignore_verify_ssl: true # true for self signed certificates
    data:
      foo: bar
    service: coolService.api
    method: GetAllFoos
    assertions:
    - result.code ShouldEqual 0
    - result.systemoutjson.foo ShouldEqual bar
```

--------------------------------

### MongoDB Extended JSON Example

Source: https://github.com/ovh/venom/blob/master/executors/mongo/README.md

Example of representing MongoDB ObjectId using Extended JSON v2 format.

```json
{
  "_id": {
    "$oid": "5d505646cf6d4fe581014ab2"
  }
}

```

--------------------------------

### User Defined Assertion Example

Source: https://github.com/ovh/venom/blob/master/README.md

Define custom assertions by prefixing an executor name with 'Should'. This example shows how to create a 'ShouldBeHttp2XX' assertion using basic comparison operators.

```yaml
# lib/ShouldBeHttp2XX.yml
executor: ShouldBeHttp2XX
steps:
  - assertions:
    - a ShouldBeGreaterThanOrEqualTo 200
    - a ShouldBeLessThan 300
```

--------------------------------

### Compile Venom with Plugin Support

Source: https://github.com/ovh/venom/blob/master/executors/plugins/odbc/README.md

Steps to clone the Venom repository, build the main binary, and compile plugin support.

```bash
$ git clone https://github.com/ovh/venom.git
$ cd venom
$ make build
$ make plugins
$ # venom binary is generated into dist directory
$ # plugin binary is generated into dist/lib directory
$ cd dist
$ ./venom run ...
```

--------------------------------

### Run Venom Tests with Various Options

Source: https://github.com/ovh/venom/blob/master/README.md

Demonstrates how to run Venom integration tests with different configurations, including output formats, variable settings, and verbosity.

```bash
venom run
```

```bash
venom run mytestfile.yml
```

```bash
venom run mytestfile.yml --format=json --output-dir=test
```

```bash
venom run mytestfile.yml --format=xml --output-dir=test --html-report
```

```bash
venom run mytestfile.yml --var="foo=bar"
```

```bash
venom run mytestfile.yml --var-from-file variables.yaml
```

```bash
VENOM_VERBOSE=2 venom run
```

--------------------------------

### Read YAML File Step

Source: https://github.com/ovh/venom/blob/master/executors/readfile/README.md

Demonstrates reading a YAML file using the read file step, with an assertion for no errors.

```yaml
name: TestSuite Read Yaml File
testcases:
  - name: Read File
    steps:
      - type: readfile
        path: yourfile.yml
        assertions:
          - result.err ShouldBeEmpty
```

--------------------------------

### Build Venom and Plugins

Source: https://github.com/ovh/venom/blob/master/executors/plugins/README.md

Commands to build the Venom binary and compile custom executor plugins.

```bash
$ make build
$ make plugins

```

--------------------------------

### Display Venom CLI Help

Source: https://github.com/ovh/venom/blob/master/README.md

Shows the main help information for the Venom CLI, listing available commands.

```bash
$ venom -h
Venom - RUN Integration Tests

Usage:
  venom [command]

Available Commands:
  help        Help about any command
  run         Run Tests
  update      Update venom to the latest release version: venom update
  version     Display Version of venom: venom version

Flags:
  -h, --help   help for venom

Use "venom [command] --help" for more information about a command.
```

--------------------------------

### Using the 'substr' filter

Source: https://github.com/ovh/venom/blob/master/variable_helpers.md

The `substr` filter extracts a portion of a string. It takes a start index and an end index (exclusive).

```go-template
name: hello-{{ .name | substr 0 5 }}
```

--------------------------------

### MustEqual Assertion Example

Source: https://github.com/ovh/venom/blob/master/README.md

Use 'MustEqual' to create a required passing assertion that prevents subsequent steps from executing if it fails. This is useful for critical checks.

```yaml
- steps:
  - type: exec
    script: exit 1
    assertions:
      - result.code MustEqual 0
  # Remaining steps in this context will not be executed
```

--------------------------------

### Keys with hyphens and unknown keys

Source: https://github.com/ovh/venom/blob/master/variable_helpers.md

Demonstrates substitution for keys containing hyphens and handling of unknown keys. Hyphenated keys are treated as literal key names.

```go-template
a {{.myvar.my-key}}.{{.myvar.foo-key}} and another key value {{.myvar.my-key}}
```

--------------------------------

### Calling User Defined Assertion

Source: https://github.com/ovh/venom/blob/master/README.md

Call a registered user assertion by its name within the 'assertions' array, similar to built-in keywords. This example uses the 'ShouldBeHttp2XX' assertion.

```yaml
# test.yml
testcases:
- steps:
  - type: http
    url: https://example.com
    assertions:
    - result.statuscode ShouldBeHttp2XX
```

--------------------------------

### Select Next Window

Source: https://github.com/ovh/venom/blob/master/executors/web/README.md

Switches focus to the next available browser window.

```yaml
- type: web
    action:
      nextWindow: true
```

--------------------------------

### Execute a Script with Standard Input

Source: https://github.com/ovh/venom/blob/master/executors/exec/README.md

Use this to provide standard input to a script. The `stdin` field accepts a string that will be piped to the script's standard input.

```yaml
name: Title of TestSuite
testcases:
- name: with stdin
  steps:
  - type: exec
    stdin: Foo
    script: cat

```

--------------------------------

### Execute a Simple Script with Assertions

Source: https://github.com/ovh/venom/blob/master/executors/exec/README.md

Use this to run a single-line script and assert its exit code and execution time. Ensure the script is simple enough for a single line.

```yaml
name: Title of TestSuite
testcases:
- name: Check if exit code != 1 and echo command response in less than 1s
  steps:
  - type: exec
    script: echo 'foo'
    assertions:
    - result.code ShouldEqual 0
    - result.timeseconds ShouldBeLessThan 1

```

--------------------------------

### DB Fixtures Executor Configuration

Source: https://github.com/ovh/venom/blob/master/executors/dbfixtures/README.md

Example YAML configuration for the dbfixtures executor in Venom. Specify the database type, connection string (DSN), schema files, and fixture folder or files.

```yaml
name: Title of TestSuite
testcases:

  - name: Load database fixtures
    steps:
      - type: dbfixtures
        database: mysql
        dsn: user:password@(localhost:3306)/venom?multiStatements=true
        schemas:
          - schemas/mysql.sql
        folder: fixtures
        files:
          - fixtures/table.yml
```

--------------------------------

### Assertions with Logical OR Operator

Source: https://github.com/ovh/venom/blob/master/README.md

Use logical operators like 'or' to perform complex assertions. This example checks if the output is equal to 1 or 2, and also demonstrates nested 'or' conditions.

```yaml
- name: Assertions operators
  steps:
  - script: echo 1
    assertions:
      - or:
        - result.systemoutjson ShouldEqual 1 
        - result.systemoutjson ShouldEqual 2
      # Nested operators
      - or:
        - result.systemoutjson ShouldBeGreaterThanOrEqualTo 1
        - result.systemoutjson ShouldBeLessThanOrEqualTo 1
        - or:
          - result.systemoutjson ShouldEqual 1
```

--------------------------------

### Next window

Source: https://github.com/ovh/venom/blob/master/executors/web/README.md

Switches the context to the next available browser window.

```APIDOC
## Next window

### Description
Select the next window
A boolean value to set to true to select next window

### Example
```yaml
  - type: web
    action:
      nextWindow: true
```
```

--------------------------------

### SSH Execution with Sudo Privileges

Source: https://github.com/ovh/venom/blob/master/executors/ssh/README.md

Shows how to execute a command with root privileges using 'sudo' and providing a specific password for it.

```yaml
- name: Execute command as another user than bar
  steps:
  - type: ssh
    host: 10.0.1.5:2222
    command: echo 'foo'
    user: bar
    sudo: root
    sudopassword: '{{.mypassword}}'
    assertions:
    - result.code ShouldEqual 0
```

--------------------------------

### SSH Execution with Specific Private Key

Source: https://github.com/ovh/venom/blob/master/executors/ssh/README.md

Demonstrates using a specific private key file for SSH authentication, overriding the default.

```yaml
- name: Use specific privatekey
  steps:
  - type: ssh
    host: 10.0.1.5:2222
    command: echo 'foo'
    user: bar
    privatekey: /home/foo/.ssh/id_rsa
    assertions:
    - result.code ShouldEqual 0
```

--------------------------------

### Run Unit Tests

Source: https://github.com/ovh/venom/blob/master/README.md

Command to execute unit tests for Venom.

```bash
make test
```

--------------------------------

### Navigate to URL

Source: https://github.com/ovh/venom/blob/master/executors/web/README.md

Navigates the browser to a specified URL. Can also reset the browser state.

```yaml
- type: web
    action:
      navigate:
        url: https://www.google.fr
```

--------------------------------

### Handle Multiline Scripts in Custom Executors

Source: https://github.com/ovh/venom/blob/master/README.md

Define a custom executor 'multilines' that accepts a script as input and executes it. This example uses the `|` operator for multiline scripts and demonstrates using the `nindent` templating function.

```yaml
executor: multilines
input:
  script: "echo 'foo'"
steps:
- type: exec
  script: {{ .input.script | nindent 4 }}
  assertions:
  - result.code ShouldEqual 0
  vars:
    all:
      from: result.systemoutjson
output:
  all: '{{.all}}'
```

--------------------------------

### Run Test Suites with Sorted Filenames

Source: https://github.com/ovh/venom/blob/master/README.md

Execute test suites by dynamically finding and sorting all YAML files in the current directory.

```bash
venom run `find . -type f -name "*.yml"|sort`
```

--------------------------------

### RabbitMQ Subscriber (Work Queue)

Source: https://github.com/ovh/venom/blob/master/executors/rabbitmq/README.md

Configure a subscriber to consume messages from a specific queue. This example sets a durable queue, a message limit, and includes assertions to validate received message body and headers.

```yaml
name: TestSuite RabbitMQ
vars:
  addrs: 'amqp://localhost:5672'
  user: 
  password: 
  - name: RabbitMQ subscribe testcase
    steps:
      - type: rabbitmq
        addrs: "{{.addrs}}"
        user: "{{.user}}"
        password: "{{.password}}"
        clientType: subscriber
        qName: "{{.qName}}"
        durable: true
        messageLimit: 1
        assertions: 
          - result.bodyjson.bodyjson0.a ShouldEqual b   
          - result.headers.headers0.mycustomheader ShouldEqual value
          - result.headers.headers0.mycustomheader2 ShouldEqual value2
          - result.messages.messages0.contentencoding ShouldEqual utf8
          - result.messages.messages0.contenttype ShouldEqual application/json
```

--------------------------------

### Load MongoDB Fixtures

Source: https://github.com/ovh/venom/blob/master/executors/mongo/README.md

Drops all collections in the database and then loads multiple collections from a folder. Each file in the folder must be named after the collection it populates.

```yaml
- type: mongo
  uri: mongodb://localhost:27017
  database: my-database
  actions:
    - type: loadFixtures
      folder: fixtures/

```

```yaml
# fixtures/cards.yml
- suit: clubs
  value: jack

- suit: clubs
  value: queen

- suit: clubs
  value: king

```

--------------------------------

### YAML Quoting Error Example

Source: https://github.com/ovh/venom/blob/master/README.md

Illustrates a common error where JSON is used directly within YAML, causing parsing issues. The fix involves using single quotes around the YAML string value.

```yaml
...
vars:
  body: >-
      {
        "the-attribute": "the-value"
      }
...
steps:
- type: http
  body: "{{.body}}"
...
```

```yaml
...
vars:
  body: >-
      {
        "the-attribute": "the-value"
      }
...
steps:
- type: http
  body: '{{.body}}'
...
```

--------------------------------

### Navigate Back

Source: https://github.com/ovh/venom/blob/master/executors/web/README.md

Navigates the browser back to the previous page in the history. Asserts the title and URL after navigation.

```yaml
- type: web
    action:
      historyAction: back
    assertions:
    - result.title ShouldStartWith GitHub
    - result.url ShouldEqual https://github.com/
```

--------------------------------

### Use Custom Executor with Multiline Script in Test Suite

Source: https://github.com/ovh/venom/blob/master/README.md

Execute a test case that utilizes the 'multilines' custom executor with a multiline script. This example shows how to define the multiline script directly within the test case.

```yaml
name: testsuite with a user executor multilines
testcases:
- name: test
  steps:
  - type: multilines
    script: |
      # test multilines
      echo "5"
    assertions:
    - result.alljson ShouldEqual 5
```