Assertions API

[nirsky]

Malabi should provide extensive and easy-to-use assertion utilities.
An issue that came up while designing the API was the fact that each test is going to assert against an array of spans.
This causes uncertainty on which span the assertion will be performed.
Here are some possible ideas that came up:

1. Reduce, then Assert

In this approach, malabi will provide a different function for extracting a single span that meets the filters, and another function for assertion.
This approach may give the most precise assertion, but is a bit confusing for the end-user, and the decision on which operator will be part of extract and which will be part of assert is a bit aribtraty.

import { extract, expect, getSpans } from 'malabi';

it('http', () => {
    const spans = getSpans();

    const httpSpan = extract(spans).http().method('post').incoming().first();
    expect(httpSpan).statusCode().toBe(200);
    expect(httpSpan).successStatusCode();
    expect(httpSpan).requestBody().toContain('admin');
    expect(httpSpan).requestHeaders('origin').toBe('http://localhost:3000');
});

it('mongo', () => {
    const spans = getSpans();

    const mongoSpan = extract(spans).mongo().second();
    expect(mongoSpan).operation().toBe('findOne');
    expect(mongoSpan).duration().lessThan(3000);
    expect(mongoSpan).statement().toHaveKey('token');
});

Another possibility for this option is that getSpans will return a span array already wrapped in extraction utils, obviating the need to use the extract function:

import { extract, expect, getSpans } from 'malabi';

it('http', () => {
    const spans = getSpans();

    const httpSpan = spans.http().method('post').incoming().first();
    expect(httpSpan).statusCode().toBe(200);
});

2. Reduce and assert in a single statement

A bit like 1, but in a single statement:

import { expect, getSpans } from 'malabi';

it('http', () => {
    const spans = getSpans();

    expect(spans).http().method('post').incoming().first().where([
        expect.statusCode(200),
        expect.successStatusCode,
        expect.requestBody.contains('admin')
    ])
});

3. Assert existence

I think this option has the easiest learning curve but lacks precision in cases where we have 2 spans that are very similar.

Style 1 - use where

import { expect, getSpans } from 'malabi';

it('mongo', () => {
    const spans = getSpans();

    expect(spans).toHaveMongo()
        .where([
            expect.operation("findOne"),
            expect.duration.lessThanMs(3000),
            expect.parentSpan.exists(),
            expect.statement.hasKey('token')
        ])
});

Style 2 - conditions object

import { expect, getSpans } from 'malabi';

it('mongo', () => {
    const spans = getSpans();

    expect(spans).toHaveMongo({
        operation: "findOne",
        duration: expect.lessThan(3000),
        parentSpans: expect.exists(),
        statement: expect.hasKey('token')
    });
});

jasmine style option

replace toHaveMongo with jasmine style, ie: expect(spans).to.have.mongo, or expect(spans).to.not.have.mongo