BLOG

Defining and Running Tests for API endpoints

May 12, 2022
   
Tutorial
Posted by Jeremy Posner

Intro

Here’s a short blog post to show how easy it is to create a test suite for your APIs inside VS Code using our RAW Extension. We’ve made it simple, as always, so that you can get maximum functionality with the minimum amount of fuss.

So let’s go….

Add Autocompletion and Validation to your YAML file

Take any YAML file previously created, or one you’re working on right now. The file I have is shown below – I created this endpoint a couple of weeks ago for a demo. You can find this on GitHub here, also:

raw: 0.9
endpoint: GET
code: rql
codeFile: ../legislators.rql
format: json
computeClass: normal
enabled: true
cacheSizeMB: 10
computeLimitSeconds: 20
declaration: male_to_female_states
metadata:
  title: Ratio of Male to Female Legislators for a set of States
  description: party and type are both optional
  tags:
    - government
    - USA
security:
  public: true
refreshSeconds: 60

First thing we’re going to do inside VS Code, and using our RAW Extension, is to add the YAML Schema validator and autocompletion capability. This ensures that we are writing correct YAML and don’t make any silly mistakes. There will be a blog post on this shortly too, but you can find more details about this in our VS Code Reference Guide.

To add this, you simply insert a line at the top of the file with VS Code’s standard ‘Trigger Suggestion’ function (either on Windows/Linux it’s CTRL+SPACE or on a Mac it’s Command+I) – then choose the snippet called: raw-import-endpoint-schema:

YAML Snippets

Now the first line of the YAML file will look something like this:

Adding the Tests

To add the tests, it’s just YAML again. I will add them to the end of the file:

Above I have added two tests, test1 that just passes a list of states to the endpoint, and test2 that passes multiple arguments. You can see that there are green tick boxes against each, to show that I have correctly specified the test.

These are now both runnable. Click on either, or both of them. The test will run, execute the endpoint and pass the parameters in. If they pass you’ll see a green tick-mark.

If they fail you will see a red circle like this, for test3 – which fails here because the function needs a required parameter states_list:

More information on Testing endpoints can be found in our excellent VS Code Extension Guide

The Testing Tab (sidebar)

After running a test, the Testing Tab opens in the sidebar. Here you can see the state of all the tests executed, which have passed, failed or are in another state.

You can execute tests here again using the run/play icon next to each test. You can also view the output from each test too, by clicking the notepad icon to the left of the play icon.

I can fix test3 now, and re-run it:

Testing that finds errors in RAW SQL code

Let’s see what happens if there’s a problem with the RAW SQL Code now. I will open up the code file where the function male_to_female_states lives, which is the function called by the YAML that returns the data:

For this test I will change the query so that it is syntactically incorrect (for instance change split to splat on line 68).

Now, Executing the Test suite again, by clicking the top play/execute icon next to tests on line 21, or also by executing the same run all tests icon in the sidebar …

I get the following screen:

I can now click on any red line, to open up error and see more details, plus I can click on the blue link to go to the file with the error in it:

Here’s the file with the error, you can see the Error message refers to line 68, where I changed the function split to splat :

Wrap Up

I hope you found this useful, and agree that adding and executing tests to API endpoints is simple and intuitive, and it’s all nicely integrated into the VS Code IDE. As usual, the code is on GitHub here.

Stay tuned for more functionality as we build out the simplest and fastest API creation and data sharing solution to share data with your colleagues internally, or your external partners, clients or suppliers. For more information, get in touch with us today, or browse our demo catalogue.

Jeremy Posner, VP Product & Solutions, RAW Labs.


Want to learn more?

Learn More

Blog

Tutorial 1. First flight with RAW

First Tutorial with RAW where we take reader through a first query, first API and passing parameters to that API

Blog

816,000 interesting FREE datasets with RAW Labs

Free Datasets are a great resource - see an example showing how to use RAW to query, transform and join with other data, then expose API endpoints for further data sharing.

Blog

NYC Taxi Cab Analytics and APIs

First in Blog Series showing New York Taxi Cab Data, how we query, clean and join this data to produce simple APIs