End to End test

Introduction

We are providing you some methods to let you test your own system in a production-like environment.

This way if your system runs fine in these test conditions, it will smoothly run in a production environment.


In this page, you'll learn how to run an end to end test.

Follow the steps and you'll be able to reproduce your specific use-case exploring multiple functionalities.

The testing environment supports all the use-cases linked to the generic commands:


START

STOP

LOCATE


Do you have a fantastic idea that you want to realize? Use this tutorial to make your dreams come true.


One last recommendation before you go: do you remember you have to do authentication and authorization? No? Check out our Guides!



Now, let's start from the beginning!


Vehicle creation

Your first move will be to create a specific number of vehicles.

The endpoint response will contain a body with an array of identifiers made of fifteen random numeric digits, which represent the IMEI codes of your testing vehicles.

Don't be lazy. You also need to register the vehicle on the testing server to start receive the events. All the testing vehicles created with this endpoint will be omni-ninebot


You'll need those to change the vehicles' statuses later on.

POST
e2e.adapter.2hire.io/devices/

The request body will consist of the following:

{
  "deviceNumber": 1
}

The success response will consist of the following:

{
    "devices": [
        "349936295960381" //IMEI fifteen random numeric code
    ]
}

In the case of a gateway connection failure, the error response will consist of the following:

{
    "code": "INTERNAL_ERROR",
    "details": {
        "cause": "INTERNAL_ERROR"
    },
    "errorId": string
}

Be careful with this endpoint! We don't want you to miss any vehicles on the road.



Vehicle state

Once you have your vehicle, you can start to change its state in order to send events to your system.

For this purpose, we'll provide you with a set of endpoints to retrieve the current values and set some new ones.

The vehicle state endpoint exposes the intrinsic vehicle's characteristics and can be used to gather the current state.

The simulated vehicle state has an initial value for each generic signal.

Later on, you'll be able to define all the values through endpoints.

The status defines the vehicle behaviour, and it'll change in response to the generic commands and through time.

So, always pay attention to your vehicle's status!


It'll be crucial in all the next steps.


The vehicle state has the following properties (reflecting the related signals):

Online

The starting value is true.

It'll change in false if the autonomy percentage goes under 0%.

Does it sound familiar to you?


Position

The starting position is predefined and embedded in our code, the vehicle sends it with a message.

Don't get scared. You'll be able to perform fantastic trips all around the world, from your home of course.


Distance covered

The starting value is 0.

The simulated trip represents a vehicle movement so it will produce an increment in the value.

We evaluate an average testing speed of 15 km/h. Every minute in trip equals an increment in the distance covered of 250 m.

Always respect the speed limits.


Autonomy percentage

The starting value is 100%.

Every minute, the value will drop off by a defined percentage, depending on the vehicle status.

LOCKED

-2%

UNLOCKED

-4%

MOVING

-8%


Don't forget your vehicle unlocked or you won't be able to go too far away.


Autonomy meters

The starting value is specific to the type of the vehicle.

The value will drop off progressively in parallel with the autonomy percentage.

A 2% drop in the autonomy percentage equals a 2% drop in the starting autonomy meters.

Too much math? You can find somewhere a fantastic calculator ready to help you.


Status

The starting status is LOCKED.

There are three possible statuses:

UNLOCKED

LOCKED

MOVING


Calling the generic commands and the trip endpoints will change the status.


START

=

LOCKED

UNLOCKED

STOP

=

UNLOCKED

LOCKED

TRIP

=

UNLOCKED

MOVING

TRIP END

=

MOVING

UNLOCKED


I'm sure you'll never pay enough attention to the vehicle status. Don't let me down!


Last locate

The starting value is undefined.

The locate command execution will update the timestamp value with the current date.


Retrieve the vehicle's state

You'll be able to recover an actual vehicle state.

GET
e2e.adapter.2hire.io/devices/:imei/state
ParameterTypeDescription
imeistringThe IMEI of the vehicle for the state you want to retrieve.

The response body will consist of the following:

{
  "position": {
    "timestamp": 1488700800000, //always set to current timestamp
    "data": {
     "longitude": -3.69623494,
     "latitude": 40.42277527,
    },
   },
  "autonomy_meters": {
    "timestamp": 1488700800000, //always set to current timestamp
    "data": {
     "meters": 800000, //max autonomy of the vehicle
    },
   },
  "distance_covered": {
    "timestamp": 1488700800000, //always set to current timestamp
    "data": {
     "meters": 0,
    },
   },
  "online": {
    "timestamp": 1488700800000, //always set to current timestamp
    "data": {
     "online": true,
    },
   },
  "autonomy_percentage": {
    "timestamp": 1488700800000, //always set to current timestamp
    "data": {
     "percentage": 100,
    },
   },
   "status": "LOCKED",
   "lastLocate": undefined,
}

Remember, the vehicle state is fundamental to simulate any possible flows.


That's a lot of information!


Vehicles are complex. Get used to it!


This set represents the most relevant information you'll need in your integration.



Vehicle functionality

The vehicle can:

  • Receive messages and generate events from all the generic commands and signals.

  • Send a heartbeat (a periodic signal to indicate normal operation) with a position within a predefined time interval.

  • Simulate a trip from a set of positions.

  • Update its status depending on an interaction.

  • Check the status to avoid incoherent operations.

    e.g. ERROR if stop in LOCKED

  • Trigger an alarm message if the trip starts in the LOCKED status.

  • Continue to change its state following the supposed behaviour even if manually set offline.

I bet now you're thinking these functionalities aren't enough for your use-cases.


Wait for the next step to discover what you'll be able to do.


Simulate a trip

You'll be able to simulate a trip with your vehicle.

You'll declare an array of positions, each position defines a point in the trip track.

POST
e2e.adapter.2hire.io/devices/:imei/trips
ParameterTypeDescription
imeistringThe IMEI of the vehicle to be modified.

Each element in the array:

  • Corresponds to a point in the trip track.
  • Updates the vehicle's position every ten seconds.
  • Generates a webhook event.

The first element triggers the start of the trip, which changes the status to MOVING.

The last element represents the stop of the trip, which changes the status to UNLOCKED.

The request body will consist of the following:

{
 "positions": [
  {
   "longitude": -3.69623494,
   "latitude": 40.42277527
  },
  {
   "longitude": -3.69623494,
   "latitude": 40.42277527
  },
  {
   "longitude": -3.69582844,
   "latitude": 40.42259979
  },
 ]
}

The success response body will consist of the following:

{
    "success": true
}

If the vehicle is in LOCKED status, the error response body will consist of the following:

{
    "success": false,
    "code": "VEHICLE_INTERACTION_ERROR",
    "details": {
        "cause": "COMMAND_FAILED"
    },
    "errorId": string
}

This is truly interesting!


A vehicle that can't move is a useless thing. Don't you agree?


Autonomy percentage

You'll be able to define a vehicle's autonomy percentage.

This will let you discharge or recharge a vehicle immediately.

POST
e2e.adapter.2hire.io/devices/:imei/state/battery
ParameterTypeDescription
imeistringThe IMEI of the vehicle to be modified.

The request body will consist of the following:

{
    "percentage": number
}

The response body will consist of the following:

{
    "success": true
}

Be careful with this parameter. Remember that it drops off through time.


We don't want you to be stuck in the middle of nowhere.


Online

You'll be able to define a vehicle's online status.

POST
e2e.adapter.2hire.io/devices/:imei/state/online
ParameterTypeDescription
imeistringThe IMEI of the vehicle to be modified.

The request body will consist of the following:

{
    "online": true
}

The response body will consist of the following:

{
    "success": true
}

It's the same old story. In these times, to be offline is like to be cut off from the world.



Errors are always around the corner.


We want to help you avoid strange situations, or catch them if it's what you're trying to do!


Potential errors

The IMEI used in the API calls has to be among those created when adding vehicles.

The error response to an API call with the wrong IMEI will consist of the following:

{
    "code": "VEHICLE_NOT_FOUND_ERROR",
    "errorId": string,
    "details": {
        "cause": "VEHICLE_NOT_REGISTERED"
    }
}

You wouldn't start a vehicle that it's not yours.


If the vehicle is LOCKED, you won't be able to start a trip.

The error response will consist in the following:

{
    "code": "VEHICLE_INTERACTION_ERROR",
    "errorId": string,
    "details": {
        "cause": "COMMAND_FAILED"
    }
}

In addition to the error response, this action will trigger an Alarm Event to the gateway, which consequently causes a webhook event.

Have you ever tried to move a locked car? It's a crime!


If the vehicle's autonomy percentage reaches 0%, it will disconnect from the gateway.

How many times did your kick scooter run out of charge, and you had to walk back home?


After 10 minutes from when the vehicle was completely discharged, it'll be removed from the service and made unavailable.

It's a strict rule, I know it. But a rule is a rule. Follow it!



Summary

In the previous sections, you can find all the elements you need to run your end to end test.


Have you realized how many unbelievable things you are now able to do?


Here is a brief recap for you.


Now you have all the tools needed to simulate real exciting use-cases.

You can easily:

  • Create your fleet.
  • Interact with each vehicle.
  • Simulate a trip with the related increment in the vehicle's distance covered.
  • Change the vehicle's status.
  • Reproduce the natural discharge of the vehicle's autonomy percentage and the related vehicle's autonomy meters.
  • Simulate the vehicle's behaviour with connection issues.

Still looking for new challenges?


I have one for you


RUN YOUR TESTS!


One last thing.

All the APIs not specific for the end to end test are equal to our production APIs.

Did you get that? The transition from test to production we'll be a piece of cake.


Did this page help you?