testpilot

testpilot is a Go package that provides a testing framework for making HTTP requests and validating responses. It is designed to help create test plans and perform assertions on HTTP requests and responses.

Features

Create and manage test plans for HTTP testing.
Perform HTTP requests with customizable methods, URLs, headers, and body content.
Validate HTTP responses with assertions on status codes, response body, and JSON paths.
Cache and retrieve responses for later use in tests.

Installation

To install testpilot, run the following command:

go get github.com/trapajim/testpilot

Usage

Creating a Test Plan

Create a new test plan using the NewPlan function:

func TestYourFunction(t *testing.T) {
    p := NewPlan(t, "test")
    p.Request("GET", "https://api.sampleapis.com/futurama/episodes").
    Expect().
    Status(200).
    Body(AssertPath(".0.id", func(val int) error {
        if val != 1 {
            return errors.New("expected 1 got " + strconv.Itoa(val))
        }
        return nil
    }))
    p.Run()
}

Adding a body and headers to the request

You can add a body and headers to the request using the Body and Headers methods:

type Episode struct {
    Id int `json:"id"`
    Title string `json:"title"`
}
func TestYourFunction(t *testing.T) {
    newEpisode := Episode{
        Id: 1,
        Title: "Space Pilot 3000",
    }
    p := NewPlan(t, "test")
    p.Request("POST", "https://api.sampleapis.com/futurama/episodes").
    Body(JSON(newEpisode)).
    Headers(map[string]string{
        "Content-Type": "application/json",
    }).
    Expect().
    Status(201)
    p.Run()
}

Utilizing Placeholder

You can utilize placeholders in the URL of the request. Placeholders are defined using curly braces {} in the URL and should be a json path. The value of the placeholder is extracted from the response of the previous request.

func TestYourFunction(t *testing.T) {
    p := NewPlan(t, "test")
    p.Request("GET", "https://api.sampleapis.com/futurama/episodes").
    Expect().
    Status(200)
    // add a second request that uses the response of the first request as a placeholder
    p.Request("GET", "https://api.sampleapis.com/futurama/episodes/{.0.id}"). // the placeholder is the id of the first episode
    Expect().
    Status(200)
    p.Run()
}

Storing and Retrieving Responses

You can store the response of a request and retrieve it later in the test plan. This is useful when you want to use the response of a request in multiple assertions.

func TestYourFunction(t *testing.T) {
    p := NewPlan(t, "test")
    p.Request("GET", "https://api.sampleapis.com/futurama/episodes").
    Store("episodes"). // store the response of this request
    Expect().
    Status(200).
    
    // add a second request that uses the stored response
    p.Request("GET", "https://api.sampleapis.com/futurama/episodes/{.0.id}"). // the placeholder is the id of the first episode
    Expect().
    Status(200).

    // add a third request, this time using the stored response
    p.Request("GET", "https://api.sampleapis.com/futurama/episodes/{episodes.1.id}"). // starting the placeholder with the name of the stored response 
    Expect().
    Status(200)

	// run the test plan
    p.Run()
}

Responses can also be used in Body method with p.Response() or p.ResponseForKey("name"):

See tests for more comprehensive examples.

Contributing

If you find a bug or want to suggest a new feature for testcraft, please open an issue on GitHub or submit a pull request. We welcome contributions from the community.