BesTest

A lightweight, powerful, and easy-to-use API testing framework for Node.js that allows you to quickly create and run tests for RESTful APIs.

Features

• Fluent API: Chain methods for readable and concise test definitions
• HTTP Methods Support: GET, POST, PUT, DELETE, PATCH
• Request Configuration: Headers, query parameters, body content, authentication
• Response Validation: Status code, body content, headers, JSON schema
• Organized Test Structure: Group tests into suites and cases
• Test Discovery: Automatically finds and runs all test files
• Detailed Reporting: Comprehensive test results with timing information

Installation

npm install bestest

Usage

Basic Example

Create a test file with .test.js extension:

import { createApiTester, createTestOrganizer } from "bestest";

const testOrganizer = createTestOrganizer("My API Tests");

testOrganizer.addTestCase("should get user details", async function () {
  const response = await createApiTester()
    .baseUrl("https://reqres.in/api")
    .path("/users/2")
    .get()
    .send();

  response.expectStatus(200)
    .expectBodyHas("data")
    .expectBodyEquals("data.id", 2);
});

export default testOrganizer;

Running Tests

npm test

API Reference

ApiTester

Creates and configures HTTP requests.

Request Configuration

createApiTester()
  .baseUrl(string) // Set the base URL
  .path(string) // Set the bestest path
  .get() // Use GET method
  .post() // Use POST method
  .put() // Use PUT method
  .patch() // Use PATCH method
  .delete() // Use DELETE method
  .header(name, value) // Add custom header
  .contentTypeJson() // Set Content-Type: application/json
  .contentTypeForm() // Set Content-Type: application/x-www-form-urlencoded
  .queryParam(key, value) // Add single query parameter
  .queryParams(object) // Add multiple query parameters
  .body(object | string) // Set JSON request body
  .formData(object) // Set form data
  .basicAuth(username, password) // Set basic authentication
  .bearerAuth(token) // Set bearer token authentication
  .timeout(milliseconds) // Set request timeout
  .send(); // Execute request and return Response object

Response

Handles HTTP response data and validation.

response
  .getStatusCode() // Get the response status code
  .getBody() // Get the response body
  .getHeaders() // Get response headers
  .expectStatus(number) // Verify status code matches expected value
  .expectBodyHas(string) // Verify response body contains key (supports dot notation)
  .expectBodyEquals(key, value) // Verify response body has key with expected value
  .expectJsonSchema(schema) // Verify response body matches JSON schema
  .expectHeaderExists(header) // Verify response contains a header
  .expectHeaderEquals(header, value) // Verify response header has expected value
  .extract(path); // Extract a value from the response body using dot notation

TestOrganizer

Organizes and runs test cases.

const testOrganizer = createTestOrganizer("Test Suite Name");
testOrganizer.addTestCase("Test case description", async function () {
  // Test code here
});

// Export the organizer
export default testOrganizer;

Examples

Testing a GET Request

testOrganizer.addTestCase("should get user list", async function () {
  const response = await createApiTester()
    .baseUrl("https://reqres.in/api")
    .path("/users")
    .queryParam("page", 2)
    .get()
    .send();

  response.expectStatus(200)
    .expectBodyHas("data")
    .expectBodyHas("page")
    .expectBodyEquals("page", 2);
});

Testing a POST Request with JSON Body

testOrganizer.addTestCase("should create user", async function () {
  const response = await createApiTester()
    .baseUrl("https://reqres.in/api")
    .path("/users")
    .post()
    .body({
      name: "John Doe",
      job: "Developer",
    })
    .send();

  response.expectStatus(201)
    .expectBodyEquals("name", "John Doe")
    .expectBodyHas("id");
});

Testing with Bearer Token Authentication

testOrganizer.addTestCase(
  "should access protected resource",
  async function () {
    const response = await createApiTester()
      .baseUrl("https://api.example.com")
      .path("/protected")
      .bearerAuth("your-token-here")
      .get()
      .send();

    response.expectStatus(200);
  },
);

JSON Schema Validation

testOrganizer.addTestCase("should validate response schema", async function () {
  const schema = {
    type: "object",
    required: ["id", "name"],
    properties: {
      id: { type: "integer" },
      name: { type: "string" },
      status: { type: "string", enum: ["active", "inactive"] },
    },
  };

  const response = await createApiTester()
    .baseUrl("https://api.example.com")
    .path("/users/1")
    .get()
    .send();

  response.expectStatus(200)
    .expectJsonSchema(schema);
});

How It Works

BesTest provides a layer of abstraction over HTTP requests with an emphasis on readability and chainability. The framework consists of several key components:

1. ApiTester: Builds and executes HTTP requests using a fluent interface
2. Response: Wraps HTTP responses with validation methods
3. TestOrganizer: Groups test cases and handles execution
4. TestRunner: Discovers and runs all test files

When you run npm test, the test runner scans for files with the .test.js extension, imports them, and executes the test cases defined in each file. Results are aggregated and displayed with detailed information about passes, failures, and execution time.

Pros and Cons

Pros

• Simple to use: Intuitive API with method chaining
• Minimal dependencies: Lightweight alternative to larger testing frameworks
• No configuration required: Works out of the box
• Focused on API testing: Specialized for HTTP API testing scenarios
• Modern JavaScript: Uses ES modules and async/await for clean code

Cons

• Limited features: Compared to comprehensive frameworks like Jest or Mocha
• Limited schema validation: Basic JSON schema validation without full JSON Schema support
• No parallel execution: Tests run sequentially
• No built-in mocking: No built-in request mocking or stubbing
• Minimal reporting formats: Console output only

Enhancement Suggestions

1. Environment Configuration: Add support for different environments (dev, staging, prod)
2. Request Mocking: Add ability to mock API responses for isolated testing
3. Response Extraction: Enhance the extraction API to support advanced patterns and transformations
4. Request/Response Logging: Add detailed logging options
5. Test Hooks: Add before/after hooks for test setup and teardown
6. Parallel Execution: Add support for running tests in parallel
7. Data-Driven Testing: Support parameterized tests with data providers
8. Test Reporters: Add support for different reporting formats (JUnit, HTML)
9. Cookie Handling: Add better support for managing cookies
10. Request Templating: Create reusable request templates

Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Please make sure to update tests as appropriate and follow the existing code style.

License

BesTest is available under the MIT license. See the LICENSE file for more info.