Kiểm tra các API web với Bộ sưu tập Postman

1. Giới thiệu

Để kiểm tra kỹ lưỡng API web, chúng tôi cần một số loại ứng dụng khách web để truy cập các điểm cuối của API. Postman là một công cụ độc lập thực hiện các API web bằng cách thực hiện các yêu cầu HTTP từ bên ngoài dịch vụ .

Khi sử dụng Postman, chúng tôi không cần phải viết bất kỳ mã cơ sở hạ tầng máy khách HTTP nào chỉ để phục vụ quá trình thử nghiệm. Thay vào đó, chúng tôi tạo các bộ thử nghiệm được gọi là bộ sưu tập và cho phép Postman tương tác với API của chúng tôi.

Trong hướng dẫn này, chúng ta sẽ xem cách tạo Bộ sưu tập người đưa thư có thể kiểm tra API REST.

2. Thiết lập

Trước khi bắt đầu với bộ sưu tập của mình, chúng tôi cần thiết lập môi trường.

2.1. Cài đặt Postman

Postman có sẵn cho Linux, Mac và Windows. Công cụ này có thể được tải xuống và cài đặt từ trang web Postman.

Sau khi loại bỏ màn hình giật gân, chúng ta có thể thấy giao diện người dùng:

2.2. Chạy máy chủ

Postman cần một máy chủ HTTP trực tiếp để xử lý các yêu cầu của nó . Đối với hướng dẫn này, chúng tôi sẽ sử dụng một dự án Baeldung trước đó, spring-boot-rest, có sẵn trên GitHub.

Như chúng ta có thể đoán từ tiêu đề, spring-boot-rest là một ứng dụng Spring Boot. Chúng tôi xây dựng ứng dụng với cài đặt mục tiêu Maven . Sau khi được xây dựng, chúng tôi khởi chạy máy chủ với mục tiêu Maven tùy chỉnh Spring-boot: run .

Để xác minh rằng máy chủ đang chạy, chúng tôi có thể nhấn vào URL này trong trình duyệt của mình:

//localhost:8082/spring-boot-rest/auth/foos

Dịch vụ này sử dụng cơ sở dữ liệu trong bộ nhớ. Tất cả các bản ghi sẽ bị xóa khi máy chủ bị dừng.

3. Tạo Bộ sưu tập Người đưa thư

Một tập hợp trong Postman là một chuỗi các yêu cầu HTTP. Postman lưu mọi khía cạnh của yêu cầu, bao gồm tiêu đề và nội dung thư. Do đó, chúng tôi có thể chạy các yêu cầu theo trình tự như các bài kiểm tra bán tự động .

Hãy bắt đầu bằng cách tạo một bộ sưu tập mới. Chúng ta có thể nhấp vào mũi tên thả xuống trên nút Mới và chọn Bộ sưu tập :

Khi hộp thoại TẠO BỘ SƯU TẬP MỚI xuất hiện, chúng tôi có thể đặt tên cho bộ sưu tập của mình là “ thử nghiệm API foo ”. Cuối cùng, chúng tôi nhấp vào nút Tạo để xem bộ sưu tập mới của chúng tôi xuất hiện trong danh sách bên trái:

Khi bộ sưu tập của chúng tôi được tạo, chúng tôi có thể di con trỏ qua bộ sưu tập đó để hiển thị hai nút menu. Nút mũi tên mở ra bảng điều khiển bên phải cung cấp quyền truy cập vào Trình chạy bộ sưu tập . Ngược lại, nút dấu chấm lửng mở menu thả xuống chứa một số thao tác trên bộ sưu tập.

4. Thêm Yêu cầu ĐĂNG

4.1. Tạo một yêu cầu mới

Bây giờ chúng ta có một bộ sưu tập trống, hãy thêm một yêu cầu vào API của chúng ta. Cụ thể, hãy gửi một tin nhắn ĐĂNG tới URI / auth / foos. Để làm điều đó, chúng tôi mở menu dấu chấm lửng trên bộ sưu tập của mình và chọn Thêm yêu cầu.

Khi hộp thoại LƯU YÊU CẦU xuất hiện, hãy cung cấp tên mô tả, chẳng hạn như “ thêm foo”. Sau đó, nhấp vào nút Lưu để kiểm tra API foo .

Khi yêu cầu được tạo, chúng tôi có thể thấy rằng bộ sưu tập của chúng tôi chỉ ra một yêu cầu . Tuy nhiên, nếu bộ sưu tập của chúng tôi chưa được mở rộng, thì chúng tôi chưa thể xem yêu cầu. Trong trường hợp đó, chúng ta có thể nhấp vào bộ sưu tập để mở rộng nó.

Bây giờ, chúng ta sẽ thấy yêu cầu mới được liệt kê trong bộ sưu tập của chúng ta. Chúng ta có thể thấy rằng yêu cầu mới, theo mặc định, là HTTP GET, không phải là những gì chúng ta muốn. Chúng tôi sẽ khắc phục điều đó trong phần tiếp theo:

4.2. Chỉnh sửa Yêu cầu

Để chỉnh sửa yêu cầu, hãy nhấp vào nó, do đó tải nó vào tab trình chỉnh sửa yêu cầu:

Mặc dù trình chỉnh sửa yêu cầu có nhiều tùy chọn, nhưng chúng tôi chỉ cần một vài tùy chọn trong số đó.

Trước tiên, hãy sử dụng menu thả xuống để thay đổi phương thức từ GET thành POST.

Thứ hai, chúng tôi cần một URL. Ở bên phải của trình đơn phương thức thả xuống là một hộp văn bản cho URL yêu cầu. Vì vậy, hãy nhập nó ngay bây giờ:

//localhost:8082/spring-boot-rest/auth/foos

Bước cuối cùng là cung cấp nội dung thư. Bên dưới địa chỉ URL là một hàng tiêu đề tab. Chúng tôi sẽ nhấp vào Body tiêu đề tab để đến biên tập cơ thể.

Trong Body tab, ngay trên vùng văn bản, có một hàng nút radio và thả xuống. Những điều này kiểm soát định dạng và loại nội dung của yêu cầu.

Dịch vụ của chúng tôi chấp nhận dữ liệu JSON, vì vậy chúng tôi chọn nút radio thô . Trong menu thả xuống bên phải, chúng tôi áp dụng loại nội dung JSON (ứng dụng / json) .

Sau khi mã hóa và kiểu nội dung đã được đặt, chúng tôi thêm nội dung JSON của mình vào vùng văn bản:

{ "name": "Transformers" }

Cuối cùng, hãy đảm bảo lưu các thay đổi của chúng tôi bằng cách nhấn Ctrl-S hoặc nhấn nút Lưu . Các Lưu nút nằm ở bên phải của Gửi nút. Sau khi lưu, chúng tôi có thể thấy rằng yêu cầu đã được cập nhật thành ĐĂNG trong danh sách bên trái:

5. Chạy Yêu cầu

5.1. Chạy một yêu cầu duy nhất

To run a single request, we just click the Send button to the right of the URL address. Once we click Send, the response panel will open below the request panel. It may be necessary to scroll down to see it:

Let's examine our results. Specifically, in the header bar, we see that our request succeeded with the status 201 Created. Furthermore, the response body shows that our Transformers record received an id of 1.

5.2. Using the Collection Runner

In contrast to the Send button, the collection runner can execute an entire collection. To launch the collection runner, we hover the cursor over our foo API test collection and click the pull-right arrow. In the pull-right panel we can see a Run button, so let's click that:

When we click the Run button the collection runner opens in a new window. Because we launched it from our collection, the runner is already initialized to our collection:

The collection runner offers options that affect the test run, but we won't need them for this exercise. Let's go directly to the Run foo API test button at the bottom and click that.

When we run the collection, the view changes to Run Results. In this view, we see a list of tests that are marked green for success and red for failure.

Even though our request was sent, the runner indicates that zero tests passed and zero tests failed. This is because we haven't added tests to our request yet:

6. Testing the Response

6.1. Adding Tests to a Request

To create a test, let's return to the request editing panel where we built our POST method. We click the Tests tab which is located under the URL. When we do that, the Tests panel appears:

In the Tests panel, we write JavaScript that will be executed when the response is received from the server.

Postman offers built-in variables that provide access to the request and response. Furthermore, a number of JavaScript libraries can be imported using the require() syntax.

There are far too many scripting features to cover in this tutorial. However, the official Postman documentation is an excellent resource on this topic.

Let's continue by adding three tests to our request:

pm.test("success status", () => pm.response.to.be.success ); pm.test("name is correct", () => pm.expect(pm.response.json().name).to.equal("Transformers")); pm.test("id was assigned", () => pm.expect(pm.response.json().id).to.be.not.null );

As we can see, these tests make use of the global pm module provided by Postman. In particular, the tests use pm.test(), pm.expect(), and pm.response.

The pm.test() function accepts a label and an assertion function, such as expect(). We're using pm.expect() to assert conditions on the contents of the response JSON.

The pm.response object provides access to various properties and operations on the response returned from the server. Available properties include the response status and JSON content, among others.

As always, we save our changes with Ctrl-S or the Save button.

6.2. Running the Tests

Now that we have our tests, let's run the request again. Pressing the Send button displays the results in the Test Results tab of the response panel:

Likewise, the collection runner now displays our test results. Specifically, the summary at the top left shows the updated passed and failed totals. Below the summary is a list that shows each test with its status:

6.3. Viewing the Postman Console

The Postman Console is a useful tool for creating and debugging scripts. We can find the console under the View menu with the item name Show Postman Console. When launched, the console opens in a new window.

While the console is open, it records all HTTP requests and responses. Furthermore, when scripts use console.log(), the Postman Console displays those messages:

7. Creating a Sequence of Requests

So far, we've focused on a single HTTP request. Now, let's see what we can do with multiple requests. By chaining together a series of requests, we can simulate and test a client-server workflow.

In this section, let's apply what we've learned in order to create a sequence of requests. Specifically, we'll add three more requests to execute after the POST request we have already created. These will be a GET, a DELETE, and finally, another GET.

7.1. Capturing Response Values in Variables

Before we create our new requests, let's make a modification to our existing POST request. Because we don't know which id the server will assign each foo instance, we can use a variable to capture the id returned by the server.

To capture that id, we'll add one more line to the end of the POST request's test script:

pm.variables.set("id", pm.response.json().id);

The pm.variables.set() function takes a value and assigns it to a temporary variable. In this case, we're creating an id variable to store our object's id value. Once set, we can access this variable in later requests.

7.2. Adding a GET Request

Now, using the techniques from previous sections, let's add a GET request after the POST request.

With this GET request, we'll retrieve the same foo instance that the POST request created. Let's name this GET request as “get a foo“.

The URL of the GET request is:

//localhost:8082/spring-boot-rest/auth/foos/{{id}}

In this URL, we're referencing the id variable that we previously set during the POST request. Thus, the GET request should retrieve the same instance that was created by the POST.

Variables, when appearing outside of scripts, are referenced using the double-brace syntax {{id}}.

Since there's no body for a GET request, let's proceed directly to the Tests tab. Because the tests are similar, we can copy the tests from the POST request, then make a few changes.

Firstly, we don't need to set the id variable again, so let's not copy that line.

Secondly, we know which id to expect this time, so let's verify that id. We can use the id variable to do that:

pm.test("success status", () => pm.response.to.be.success ); pm.test("name is correct", () => pm.expect(pm.response.json().name).to.equal("Transformers")); pm.test("id is correct", () => pm.expect(pm.response.json().id).to.equal(pm.variables.get("id")) );

Since the double-brace syntax is not valid JavaScript, we use the pm.variables.get() function to access the id variable.

Finally, let's save the changes as we've done before.

7.3. Adding a DELETE Request

Next, we'll add a DELETE request that will remove the foo object from the server.

We'll proceed by adding a new request after the GET, and setting its method to DELETE. We can name this request “delete a foo“.

The URL of the delete is identical to the GET URL:

//localhost:8082/spring-boot-rest/auth/foos/{{id}}

The response will not have a body to test, but we can test the response code. Therefore, the DELETE request will have only one test:

pm.test("success status", () => pm.response.to.be.success );

7.4. Verifying the DELETE

Finally, let's add another copy of the GET request to verify that the DELETE really worked. This time, let's duplicate our first GET request instead of creating a request from scratch.

To duplicate a request, we right-click on the request to show the dropdown menu. Then, we select Duplicate.

The duplicate request will have the word Copy appended to its name. Let's rename it to “verify delete” to avoid confusion. The Rename option is available by right-clicking the request.

By default, the duplicate request appears immediately after the original request. As a result, we'll need to drag it below the DELETE request.

The final step is to modify the tests. However, before we do that, let's take an opportunity to see a failed test.

We have copied the GET request and moved it after the DELETE, but we haven't updated the tests yet. Since the DELETE request should have deleted the object, the tests should fail.

Let's make sure to save all of our requests, then hit Retry in the collection runner. As expected, our tests have failed:

Now that our brief detour is complete, let's fix the tests.

By reviewing the failed tests, we can see that the server responds with a 500 status. Therefore, we'll change the status in our test.

Furthermore, by viewing the failed response in the Postman Console, we learn that the response includes a cause property. Moreover, the cause property contains the string “No value present“. We can test for that as well:

pm.test("status is 500", () => pm.response.to.have.status(500) ); pm.test("no value present", () => pm.expect(pm.response.json().cause).to.equal("No value present"));

7.5. Running the Full Collection

Now that we've added all of the requests, let's run the full collection in the collection runner:

If everything has gone according to plan, we should have nine successful tests.

8. Exporting and Importing the Collection

While Postman stores our collections in a private, local location, we may want to share the collection. To do that, we export the collection to a JSON file.

The Export command is available within the ellipsis menu of the collection. When prompted for a JSON file version, let's choose the latest recommended version.

After we select the file version, Postman will prompt for a file name and location for the exported collection. We can choose a folder within our GitHub project, for example.

To import a previously exported collection, we use the Import button. We can find it in the toolbar of the main Postman window. When Postman prompts for a file location, we can navigate to the JSON file we wish to import.

It's worth noting that Postman does not track exported files. As a result, Postman doesn't show external changes until we re-import the collection.

9. Conclusion

Trong bài viết này, chúng tôi đã sử dụng Postman để tạo các bài kiểm tra bán tự động cho REST API. Mặc dù bài viết này đóng vai trò là phần giới thiệu về các tính năng cơ bản của Postman, nhưng chúng tôi hầu như chưa sơ lược về khả năng của nó. Tài liệu trực tuyến của Người đưa thư là một nguồn tài nguyên quý giá để khám phá sâu hơn.

Bộ sưu tập được tạo trong hướng dẫn này có sẵn trên GitHub.