CUTE HTTP and REST API Testing Framework for Go

CUTE allows implementing custom assertions at three different levels of complexity:

1. Base Asserts

Simple functions that return an error if the assertion fails. Use these for standard logic.

• AssertBody func(body []byte) error
• AssertHeaders func(headers http.Header) error
• AssertResponse func(response *http.Response) error

2. T Asserts (Allure & Testing.TB integration)

These allow you to use cute.T to log information to Allure, create steps, and use require style assertions.

• AssertBodyT func(t cute.T, body []byte) error
• AssertHeadersT func(t cute.T, headers http.Header) error
• AssertResponseT func(t cute.T, response *http.Response) error

3. Custom Assert Errors

To create detailed, pretty errors in Allure, use the cute/errors package:

• errors.NewAssertError(name, message, params, ...): Creates a structured assertion error.
• errors.NewOptionalError(err): Creates an error that causes the step to fail but allows the overall test to pass.

// Example of a Base Assert
func customAssertBody() cute.AssertBody {
    return func(bytes []byte) error {
        if len(bytes) == 0 {
            return errors.New("response body is empty")
        }
        return nil
    }
}

// Example of a T Assert with Allure steps
func customAssertBodySuite() cute.AssertBodyT {
    return func(t cute.T, bytes []byte) error {
        step := allure.NewSimpleStep("Custom assert step")
        defer func() {
            t.Step(step)
        }()

        if len(bytes) == 0 {
            step.Status = allure.Failed
            step.Attachment(allure.NewAttachment("Error", allure.Text, []byte("response body is empty")))
            return nil
        }
        return nil
    }
}

You can execute a collection of tests using two different patterns. Both patterns produce identical Allure reports.

1. Builder table tests: Use cute.NewTestBuilder() to configure metadata (Title, Tag, Description), call CreateTableTest(), provide tests via PutTests(...), and execute them with ExecuteTest(ctx, t).
2. Array tests: Manually iterate over a slice of *cute.Test and call test.Execute(ctx, t) on each element.

Both methods allow you to define a slice of *cute.Test objects containing Name, Middleware, Request (with Builders), and Expect configurations.

// Builder pattern
cute.NewTestBuilder().
    Title("Example table test").
    Tag("table_test").
    Description("Execute array tests").
    CreateTableTest().
    PutTests(tests...).
    ExecuteTest(context.Background(), t)

// Array pattern
for _, test := range tests {
    test.Execute(context.Background(), t)
}

For large test collections, use suite.Suite (from allure-go) to organize tests.

1. Define a struct that embeds suite.Suite and includes a *cute.HTTPTestMaker.
2. Implement BeforeAll(t provider.T) to initialize the testMaker and common resources (like a base URL).
3. Define test methods on the struct using provider.T.
4. Run the suite using suite.RunSuite(t, new(YourSuiteStruct)).

import (
    "github.com/ozontech/cute"
    "github.com/ozontech/allure-go/pkg/framework/provider"
    "github.com/ozontech/allure-go/pkg/framework/suite"
    "net/url"
)

type ExampleSuite struct {
    suite.Suite
    host *url.URL
    testMaker *cute.HTTPTestMaker
}

func (i *ExampleSuite) BeforeAll(t provider.T) {
    i.testMaker = cute.NewHTTPTestMaker()
    host, _ := url.Parse("https://jsonplaceholder.typicode.com/")
    i.host = host
}

func (i *ExampleSuite) TestExample_OneStep(t provider.T) {
    testBuilder := i.testMaker.NewTestBuilder()
    testBuilder.Title("One Step").Create()...
}

func TestExampleTest(t *testing.T) {
    suite.RunSuite(t, new(ExampleSuite))
}

Use cute.NewTestBuilder() to create a single-request test. You can define the title, description, request parameters (URI, method, headers), and expectations (status code, timeouts, body assertions) before executing the test with ExecuteTest.

import (
    "context"
    "net/http"
    "testing"
    "time"

    "github.com/ozontech/cute"
    "github.com/ozontech/cute/asserts/json"
)

func TestExample(t *testing.T) {
    cute.NewTestBuilder().
        Title("Title").
        Description("some_description").
        Create().
        RequestBuilder(
            cute.WithURI("https://jsonplaceholder.typicode.com/posts/1/comments"),
            cute.WithMethod(http.MethodGet),
        ).
        ExpectExecuteTimeout(10*time.Second).
        ExpectStatus(http.StatusOK).
        AssertBody(
            json.Equal("$[0].email", "Eliseo@gardner.biz"),
            json.Present("$[1].name"),
        ).
        ExecuteTest(context.Background(), t)
}

You can chain multiple requests within a single test by using NextTest(). To pass data between steps (e.g., capturing a status code or body from the first request to use in the second), use AfterTestExecute.

import (
    "context"
    "fmt"
    "net/http"
    "testing"

    "github.com/ozontech/cute"
)
    
func Test_TwoSteps(t *testing.T) {
    responseCode := 0

    // First step
    cute.NewTestBuilder().
        Title("Test with two requests and parse body.").
        Tag("two_steps").
        Create().
        RequestBuilder(
            cute.WithURI("https://jsonplaceholder.typicode.com/posts/1/comments"),
            cute.WithMethod(http.MethodGet),
        ).
        ExpectStatus(http.StatusOK).
        NextTest().

        // Execute after first step and parse response code
        AfterTestExecute(func(response *http.Response, errors []error) error { 
            responseCode = response.StatusCode

            return nil
        }).

        // Second step
        Create().
        RequestBuilder(
            cute.WithURI("https://jsonplaceholder.typicode.com/posts/2/comments"),
            cute.WithMethod(http.MethodDelete),
        ).
        ExecuteTest(context.Background(), t)

    fmt.Println("Response code from first request", responseCode)
}