import static com.apisimulator.embedded.SuchThat.*;
import static com.apisimulator.embedded.http.HttpApiSimulation.*;
import static com.apisimulator.http.Http1Header.*;
import static com.apisimulator.http.HttpMethod.*;
import static com.apisimulator.http.HttpStatus.*;
import com.apisimulator.embedded.http.HttpApiSimulation;
Initializing a Simulation
Imports
Add these imports when using the Embedded API Simulator. You may not need all of them depending on whether you use the predefined constants for various HTTP elements like methods (verbs), statuses, and header names.
We decided not to pack everything in a way that all to import is a single class. We value code maintainability and think that having 2-3 more import statements, as needed, is better for supportability.
HTTP API Simulation
To simulate an HTTP API we first get HTTP API Simulation object that starts an API Simulator instance listening on a local port.
You may have guessed from the import statements above that an embedded HTTP API Simulation object is of type com.apisimulator.embedded.http.HttpApiSimulation
. The simplest way to get an HTTP API Simulation object for a simulation named "my-awesome-simulation" is as follows:
httpApiSimulation("my-awesome-simulation");
That is equivalent to this:
httpApiSimulation("my-awesome-simulation", usingApiSimulator().instance());
Both create HTTP API Simulation object, which uses an API Simulator instance that is listening on the default port 6090
.
We can define different port number. For example:
httpApiSimulation("my-awesome-simulation", usingApiSimulator().onPort(8080).instance());
Some hosts may have multiple network interfaces. This is how we can configure API Simulator to bind to a particular local IP:
httpApiSimulation("my-awesome-simulation",
usingApiSimulator().onPort(8888).onHost("172.30.0.12").instance()
);
There is no limitation on using only one API Simulation instance at any given time. Just configure their API Simulators to listen on different port numbers. |
Lifecycle Management
Below we take a quick look at the options to define, initialize, and shut down an HTTP API Simulation.
JUnit Class Rule
Using the JUnit’s @ClassRule
annotation is a convenient way to have the simulation initialized and started before the execution of any test method in a test class and stopped after the last method’s execution completes. Here is how to use it:
@ClassRule
public static final JUnitHttpApiSimulation clApiSimulation =
JUnitHttpApiSimulation.as(httpApiSimulation("payment-tests-api-simulation"));
Notice that per the @ClassRule
annotation requirements, the field must be public
and static
.
JUnit Rule
Using the JUnit’s @Rule
annotation causes the simulation to be re-initialized and started before the execution of each test method and automatically shut down after the method completes:
@Rule
public final JUnitHttpApiSimulation mApiSimulation =
JUnitHttpApiSimulation.as(httpApiSimulation("junit-rule-simulation"));
Notice that per the @Rule
annotation requirements, the field must be public
and not static
.
JUnit Member Instance
Using @Rule
annotation may not be an option in some cases. To accomplish the same functionality, explicitly create the simulation in method annotated with @Before
or named setUp()
, and stop the simulation in method annotated with @After
or named tearDown()
:
private HttpApiSimulation mApiSimulation = null;
@Before
public void setUp()
{
mApiSimulation = httpApiSimulation("reinitialized-simulation");
}
@After
public void tearDown()
{
if (mApiSimulation != null)
{
mApiSimulation.stop();
}
}
Method Instance
Use method-scoped HTTP API Simulation instance to simulate remote APIs called within a method but not needed outside of it. Employing try..finally
assures the simulation’s API Simulator is shutdown at the end and the port it was listening on is freed up even in case of an exception.
public void myMethod()
{
...
HttpApiSimulation apiSim = null;
try
{
apiSim = httpApiSimulation("method-scoped-simulation");
apiSim.add(simlet("simlet-1")
.when(...)
.then(...)
);
apiSim.add(simlet("simlet-2")
.when(...)
.then(...)
);
...
}
finally
{
if (apiSim != null)
{
apiSim.stop();
}
}
}
Static Instance
Defining an HTTP API Simulation instance as static
in a class (and not annotated with @ClassRule
) will start its API Simulator when the class is initialized. Shutting down the JVM will shut down the API Simulator and free up the port it was listening on.
public static final HttpApiSimulation clApiSimulation = httpApiSimulation("global-simulation");
We would love to hear your feedback - send us a quick email to [feedback at APISimulator.com]
Happy API Simulating!