Implementing Step Endpoints
After defining steps in the OpenAPI spec, you will need to implement the code for all the endpoints that will execute their respective steps. This work is akin to writing "step definitions" or "glue code" in BDD test frameworks like Cucumber. The general steps for implementing the steps include:
- Creating a new project
- Generating boilerplate code
- Implementing handler functions
- Testing step endpoints
The precise operations for each step will depend upon the programming language chosen for the project.
Creating a new project
A step plugin is a web service that needs its own project. You will need to create the appropriate project structure for the chosen programming language. If you are using Java, you can use Spring Initializr to create a new Spring Boot project. Furthermore, it is strongly recommended to manage your step plugin project as a Git repository so that it is protected by source code management.
Generating boilerplate code
Web service projects typically need a fair amount of code to set up routes, inputs, and handlers (or "callbacks"). Thankfully, OpenAPI code generators can generate much of that boilerplate code. There are OpenAPI code generators for many different languages and web frameworks. In general, they work by reading the OpenAPI spec file and generating code in the target language that sets up each route with its inputs. Then, you as the plugin developer simply need to implement the handler function for each route, which should contain the logic to run each respective step. The code generators let you spend less time writing repetitive web framework code and more time writing step logic. They also protect against mistakes in routes and inputs.
Below are recommended OpenAPI code generators for step plugins:
Language | OpenAPI Code Generator | Usage Guidelines |
---|---|---|
Go | oapi-codegen | Works as a command line tool. Generates server-side code for several Go web frameworks including Gin as well as HTTP models. Endpoint handlers must implement generated interfaces and register handlers. |
Java | openapi-generator-maven-plugin | Works as a Maven plugin. Generates boilerplate code for Spring Boot into the target directory. Endpoint handlers must implement generated interfaces. |
Implementing handler functions
The handler functions/methods (sometimes called "callbacks") must encode the logic for performing the steps. For example, the handler for the Web step When I navigate to "https://cyclelabs.io/" in web browser
should perform the following operations:
- Receive the URL input value, which is likely provided to the handler through the generated code.
- Retrieve the step plugin's Selenium WebDriver session for the current test.
- Call the WebDriver method to navigate to the given URL.
- Return the step's response object indicating if the navigation was a success or failure.
Every handler will require unique logic. Writing this logic will probably the the most challenging part of developing the step plugin.
Testing step endpoints
New steps should be thoroughly tested before the plugin is released for testers to use as part of Cycle. The test frameworks and packages to use will depend upon the chosen programming language, but in general, step plugin developers should enact a multi-layered testing strategy:
- Automate unit tests for non-boilerplate functions/methods.
- Automate integration tests for calling step handlers.
- For simplicity, you could write white-box tests that call handler methods/functions internally.
- Alternatively, you could write black-box API tests that send HTTP requests to the endpoints.
- Automate end-to-end tests by writing CycleScript feature files that call the plugin's steps.
- This will require adding the step plugin to Cycle.
If your step plugin will contain several steps, it is recommended to implement steps in small batches. Implement a few steps at a time, plug the latest build into Cycle, and test the steps iteratively. That way, you will catch problems early and deliver new steps readily.