Forem: Jordan Walsh

Quickly Testing your Custom Spectral Rules

Jordan Walsh — Thu, 10 Nov 2022 02:15:23 +0000

I recently started playing with Spectral for validating OpenAPI & AsyncAPI specifications against a common set of rules.

Whilst Spectral is a very powerful tool, the experience of actually writing the rules (and getting them correct) had a steep learning curve.

I found a lot of code based testers and validators that did help, but there was no open source online editor to help write and validate your rules - so I built one!

Check out my Governance Rules Playground here - https://governance-rules-playground.postmansolutions.com/

Have a look and let me know if you find it useful in writing your Spectral rules.

Github Repo: https://github.com/postman-solutions-eng/governance-rules-playground

Run Postman Mock Servers on Localhost

Jordan Walsh — Sun, 14 Aug 2022 01:16:44 +0000

Updated April 2024

One of Postman's many wonderful features is its ability to run a Postman Collection as a callable Mock Server with a few simple clicks.

Postman Mock Servers provide two major benefits:

Removing dependencies

Coding against mock servers removes a dependency on downstream APIs being available. Instead developers can build configure the mock servers, specify the examples that they want to be returned and implement their code to handle these use cases.

Likewise API testers are unblocked as they can write and validate their API tests against the mock servers and only switch to hitting real endpoints when the developers have deployed stable (testable) code.

Collaboration on expected state

Mock servers are a great way for teams to collaborate on the expected inputs and outputs of an API.

There's nothing quite like hitting an endpoint to see exactly what it's going to return. This is taken to the next level when developers, testers and consumers of an API are all given access to the same mock server. Everyone is seeing the same expected state, and everyone has a common shared goal.

All in all these are great features to have as part of any modern development lifecycle.

So what's the issue then?

One challenge with this is that even after removing a dependency on a downstream API provider you are still at the whim of Postman.

Postman's mock servers run on Postman's cloud (AWS), so if you are working in an environment where external internet access is tricky, or you simply need to run your mock servers closer to your client code, Postman Local Mock Server is the answer.

Postman Local Mock Server

This is a simple javascript package that you can import into your codebase to run a collection as a local server.

Pick the port you want it to run on and supply a collection JSON file and the postman-local-mock-server package will run it for you.

Getting Started

Step 1
Create a collection using Postman (or pick one from the Public API Network).

The only requirement here is that for every request in your collection you need to specify at least one example response with a valid status code.

The mock server will use the combination of paths and headers to determine which example response is the best to return, but you can also control this with some parameters.

Step 2
Install the dependency from npm.

npm install -g @jordanwalsh23/postman-local-mock-server

Step 3
Run the collection.

postman-local --collection <path-to-collection> --port 3555

Step 4
Send some API requests!

You can use any API Client (even #postman) or your application code to hit the endpoints on http://localhost:3555.

The server will automatically respond with the mocked examples you created in your collection.

How do I pick the response I want to come back?

There are 4 optional headers that you can supply in your requests to the local mock server to get it to respond how you want.

x-mock-response-name - Send this with the name of a specific response you want returned.

x-mock-response-code - Send this with the status code you would like returned from the API. If there is a matching example with this status code it will be returned.

x-mock-response-id - Send this with the ID of a specific example response you want returned. This ID is the internal Postman ID so you will need to look at the collection or use Postman's API to find this out.

x-mock-match-request-body - (Boolean, Default: false) If you are using POST/PUT/PATCH requests that have a body, you can use the following header to get the Postman Local Mock Server to match the body on one of your example responses.

Postman supports dynamic response data in mocks, does this?

Yes! If you use some of the faker library fields that Postman supports these will also resolve in the Postman Local Mock Server.

What about collection, environment and global variables?

The library doesn't currently support variables. Maybe in a future release if this is needed.

Does it run pre-request and test scripts?

No. Unfortunately not. If this is needed please raise an issue on the repo.

Feedback/Comments/Questions

Please feel free to create an issue on the repo if you have some feedback.

Thanks!

Shifting Left with Postman

Jordan Walsh — Thu, 11 Aug 2022 07:41:08 +0000

This article was written by Jordan Walsh.

Successful organizations today understand that when quality-focused activities are started early in software development projects, it leads to significant benefits—not only in reducing the number of defects deployed to production systems, but also in customer satisfaction and overall team morale.

This idea, known as “shifting left,” has been around for many years. Still, many organizations remain hesitant to embrace the idea, either because the benefits are not understood well or because it’s seen as too difficult to change current processes.

While technology teams implement the shift-left approach, it requires support from management to allow teams the flexibility to move into this way of operating. Management must be prepared to allow development and quality-focused teams the space to make mistakes and potentially procure necessary tools and software to support them on this journey.

Today, Postman is the world’s leading API platform helping more than 20 million registered developers with their API lifecycle needs. Organizations using Postman to shift left their development and testing practices are seeing amazing benefits, including:

Increased efficiency in the development and testing processes
Increased NPS score from user feedback and surveys
Increased performance of their applications
Reduction in software defects being raised during actual testing cycles
Reduction in security vulnerabilities
Reduction in time to ship products

4 ways Postman helps you shift left

Here are four ways you can use the Postman API Platform to get started with shifting left your development and quality practices:

1. Authoring API specifications in Postman

Postman’s API Builder provides developers a great interface for managing and maintaining API specifications. Specifications can be developed directly in Postman, imported from JSON/YAML files, or synchronized from Git code storage systems.

Along with integrated error detection, Postman’s API Builder provides intelligent security warnings to inform API designers during design time of any security flaws that are detected in API specifications—even on specs developed in other tools. Having these picked up during design time drastically reduces the impact these types of errors can cause when they make their way into production.

Authoring API definitions in Postman’s API Builder

Postman’s API Builder helps developers:

Store and manage design assets for APIs
Find errors in API specifications early
Be warned about security issues and provides appropriate advice on correction

API specifications that are available in Postman form the starting point for a structured API-first lifecycle through generation of Postman Collections for different use cases.

2. Generating mock servers with customizable examples

Mock servers are a very useful way for developers and quality teams to do shift-left testing of their applications. With a few clicks, a mock server can be created that mimics the behavior of the API, simulating sample responses in both success and error conditions.

Mock server example responses generated instantly in Postman

When used as part of a development lifecycle, the generated examples can be leveraged by user interface developers to provide data that will be displayed within their applications. On top of this, Postman provides the ability to update the example content almost instantly without any deployment. This rapid development approach allows teams to quickly understand the effect on the UI when different circumstances occur (e.g., large datasets, no data returned, error conditions, and more).

Postman’s mock servers help developers:

Mimic the behavior of an API without writing any code
Generate customizable examples that can be used in other parts of the application

Mock servers form a key part of shifting the quality left when writing API-driven applications.

3. Collaboration on test cases between developers and quality teams

With the addition of mock servers into the development lifecycle, quality teams can begin writing their test cases immediately, removing any dependency on the development teams to complete the build of their code.

Postman provides a collaborative space to create and house these tests, giving them context by aligning them to specific APIs and requests, and at the same time allowing development teams to watch the progress of the tests and use Postman to execute these test cases directly on their local development servers. Developers can then comment and provide feedback on the test cases in real time, ensuring a dialogue between the teams.

Simplifying creating and collaborating on tests in Postman

Using Postman environments, the quality team can write all necessary test cases and run these against mock servers. Once the code has been built and delivered into a shared QA server, a new Postman environment can be created to point the test cases to this new server and execute them there.

Giving quality teams the ability to quickly switch test cases between mock servers and live servers ensures that they are able to identify differences quickly and call out where there might be defects in the code. Giving developers access to these tests while they are being written will enable both the developers and quality teams the ability to discuss and determine if the tests are being written in the most efficient and effective way.

Creating and updating environments in Postman

Postman’s collaboration tooling helps developers:

Start writing test cases early to speed up the quality cycles on code
Collaborate on tests and ensure they are being written effectively
Test the same thing against many different environments (from local to production)

4. Monitor-driven API tests with data visibility

Once quality teams write tests, it is common for these tests to be shelved until the next regression testing cycle, with development and quality teams moving on to the next release.

The challenge with this approach is that any bugs that make their way into the production environment are often identified by customers through support tickets, resulting in a poor customer experience, and development cycles being interrupted by bug fixes.

With Postman, the tests that were written can be linked to a Postman monitor and be executed on a regular basis, with test results synchronized into operational monitoring systems (such as DataDog or PagerDuty).

Viewing monitoring results and connecting APM systems in Postman

This is a continuation of shifting quality left, as you are continuing to ask your quality team to make sure that not only the quality of what is being built is at a high standard, but also what has been built before. By reusing the tests from the previous releases, your quality teams can have confidence that the quality of deployed code remains high, and any defects that are released are known before your customers see them.

Postman’s monitoring tooling helps developers:

Use existing tests to run on a schedule against deployed systems
Identify issues before customers find them, resulting in a better customer experience
Have confidence in the quality of deployed code

Conclusion

Shifting left is a concept that can be applied to improve the quality of not just technical applications, but also the way that services and user interfaces are designed. It is the idea of moving the actual building of systems as far right as possible in order to spend more time on design and quality-focused initiatives.

Taking part in a shift-left movement of quality is not the responsibility of just the quality team or the development team. This requires an investment from everyone in the development lifecycle, from management all the way down.

The investment in this approach may take some time to prove results, but it is likely to yield quality improvements in products, better customer experience, and an overall improvement in employee morale as there will be less time in maintaining defective code and more time in the development of new features.

As described above, the Postman API Platform provides a range of features and functions that can assist development and quality teams on shifting testing processes left, including API Builder tooling, mock servers, collaboration, and automated test-driven monitors. Postman allows teams to get started with very little friction and achieve a massive boost to productivity and quality.

The post Shifting Left with Postman was written by Jordan Walsh and appeared first on Postman Blog.