Observable API Testing with YAML using Echoed

Introduction

I'm building a package that makes integration testing easy by visualizing OpenTelemetry's traces and logs.

GitHub is 👉 👉 https://github.com/mrasu/echoed

What is Echoed

Echoed enhances Integration testing, aka API testing by visualizing OpenTelemetry's traces and logs.
Because it is built on top of Jest, it holds Jest's features like parallel execution or debuggability.
In addition to those features, Echoed offers unique capabilities:

• Coverage Analysis: Gain insights into the coverage of your API endpoints based on OpenAPI or Protocol Buffers specifications.
• Detect Propagation Leaks: Uncover spans that don't propagate OpenTelemetry's context to their children.
• etc.

This is an overview of Echoed

Echoed now suppors YAML!

Because Echoed is working with Jest, JavaScript and TypeScript are originally supported.
And now, you can also write tests with YAML!
With this, you can create tests with less effort and it requires little knowledge about JavaScript or TypeScript.

YAML is like below:

variable:
  productId: OLJCESPC7Z
scenarios:
  - name: Get product detail
    steps:
      - description: fetch /products/{id}
        act:
          runner: fetch
          argument:
            endpoint: http://localhost:8080/products/${productId}
        assert:
          - expect(_.response.status).toBe(200)
          - expect(_.jsonBody.id).toBe(productId)

In the above YAML.
The test does:

• Create a request to http://localhost:8080/products/${productId}
• Check status code of the response is 200
• Check body of the response is JSON and value of id in the JSON is OLJCESPC7Z

After writing the YAML, Echoed compiles it to TypeScript using npx echoed compile.
Then, you can run test by npx jest without knowing TypeScript for it.

Additionally, Echoed generates an HTML report for the tests.
It contains OpenTelemetry's data and coverage for each service.

Here are the screenshots of these features

Complex example

When you want to tests more complicated flow like retry or set up database, Echoed supports them.
Below YAML does more things:

retry: 3 # <- retry failed tests.
variable:
  productId: OLJCESPC7Z # <- define variables.
  db: ${connectDB()}
runners:
  - runner: fetch
    option:
      baseEndpoint: ${_env.BASE_ENDPOINT}/api
      headers:
        content-type: application/json
hook:
  beforeEach: # <- set up DB before each test
    - db.insertProduct(productId)
  afterEach:
    - db.cleanup() # <- clear DB
scenarios:
  - name: Adding item to cart
    variable:
      userId: 1234
    steps:
      - description: Add a product to cart
        arrange:
          - db.createUser(userId) # <- establish preconditions
        act:
          runner: fetch # <- executes HTTP request
          argument:
            endpoint: cart?currencyCode=USD
            method: POST
            jsonBody:
              item:
                productId: ${productId}
                quantity: 1
              userId: ${userId}
        assert:  # <- test anything
          - expect(_.response.status).toBe(200)
          - |
            expect(_.jsonBody).toEqual({
              items: [{
                productId: productId,
                quantity: 1
              }],
              userId: userId,
            })

It does,

• Create required data in beforeEach
• Establish preconditions in arrange
• Create an HTTP request in act
• Check the response is what you want in assert
• Then delete data in afterEach

Echoed's YAML respects the AAA(Act-Arrange-Assert) pattern. So you can separate code for preparing data and code that actually you want to test.

You can see more examples at GitHub

Bonus. Using Echoed without OpenTelemetry

While the primary feature of Echoed is troubleshooting or analyzing tests by visualizing OpenTelemetry data, it can also be used to write Jest tests in YAML.
Because conversion from YAML to Jest test (TypeScript) doesn't use OpenTelemetry, even when you haven't had time to install OpenTelemetry to you project, you can write tests with YAML using Echoed.

---

That's all!
Echoed has more features making test easy.
Visit GitHub! 👉👉 https://github.com/mrasu/echoed 👈👈

I'd appreciate any feedback – whether you liked it or not!