fluentrest-ts

A lightweight, fluent TypeScript API testing library inspired by Java's RestAssured. Built on top of Axios, JSONPath, and Joi for powerful request handling and response validation.

---

📦 Installation

1npm install fluentrest-ts

---

🚀 Quick Start

1import { fluentRest } from "fluentrest-ts";
2
3const response = await fluentRest()
4  .setBaseUrl("https://jsonplaceholder.typicode.com")
5  .givenHeader("Accept", "application/json")
6  .whenGet("/posts/1");
7
8response
9  .thenExpectStatus(200)
10  .thenExpectBody("$.id", 1);

❗️ Note: thenExpectX methods require the result of a request (you must await the whenX() call).

---

🔁 Fluent API Overview

Method	Description
setBaseUrl(url)	Sets the base URL
setTimeout(ms)	Overrides timeout
setLogLevel(level)	Sets log verbosity ("debug" | "info" | "none")
enableFileLogging(bool)	Enables or disables file-based logging
givenHeader(key, value)	Adds a request header
givenQueryParam(key, value)	Adds a query parameter
givenBody(obj)	Sets JSON request body
givenFormData(fields)	Attaches multipart form-data or files
debug()	Prints current config to console
getSnapshot()	Returns snapshot of current request config
whenGet(url)	Sends a GET request
whenPost(url)	Sends a POST request
whenPut(url)	Sends a PUT request
whenPatch(url)	Sends a PATCH request
whenDelete(url)	Sends a DELETE request
whenHead(url)	Sends a HEAD request
whenOptions(url)	Sends an OPTIONS request
sendAndExpect(method, url, fn, overrides?)	Sends a request and runs assertions

---

✅ Response Validator API

After each request, you receive a ResponseValidator object with the following methods:

Method	Description
thenExpectStatus(code)	Assert HTTP status code
thenExpectBody(path, val)	Assert JSONPath value
thenExpectBodyContains(fragment)	Assert body contains key-values
thenValidateBody(schema)	Joi schema validation
thenExpectHeader(k, v)	Assert response header
thenExtract(path)	Extract JSONPath value
catchAndLog(fn)	Wrap and log assertion failures
getResponse()	Raw Axios response
getRequestConfig()	Request config used
wasFailure()	True if request failed

---

🧪 Examples by Method

POST with JSON and Assertions

1await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .givenBody({ title: "foo", body: "bar", userId: 1 })
4  .whenPost("/posts")
5  .thenExpectStatus(201)
6  .thenExpectBody("$.title", "foo");

GET with Query Params

1await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .givenQueryParam("userId", "1")
4  .whenGet("/posts")
5  .thenExpectStatus(200);

PUT with Header

1await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .givenHeader("Authorization", "Bearer token")
4  .givenBody({ title: "updated title" })
5  .whenPut("/posts/1")
6  .thenExpectStatus(200);

PATCH and Body Fragment Check

1await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .givenBody({ title: "patched" })
4  .whenPatch("/posts/1")
5  .thenExpectBodyContains({ title: "patched" });

DELETE

1await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .whenDelete("/posts/1")
4  .thenExpectStatus(200);

HEAD

1await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .whenHead("/posts/1")
4  .thenExpectStatus(200);

OPTIONS

1await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .whenOptions("/posts")
4  .thenExpectStatus(204);

---

🧩 Logging

1await fluentRest()
2  .enableFileLogging(true)
3  .setLogLevel("debug")
4  .whenGet("/posts/1")
5  .thenExpectStatus(200);

Log levels:

• "debug" – log everything
• "info" – request + response
• "none" – silence

Logs are written to logs/restassured-<pid>.log by default unless overridden via configureDefaults.

---

🛠️ Global Defaults

1import { configureDefaults } from "fluentrest-ts";
2
3configureDefaults({
4  timeout: 15000,
5  logLevel: "info",
6  logFilePath: "logs/custom.log",
7});

You may also use .env variables:

RA_TIMEOUT=20000
RA_LOG_LEVEL=debug
RA_LOG_FILE=logs/run.log
RA_BASE_URL=https://jsonplaceholder.typicode.com

Ensure .env is loaded before any fluentrest-ts import.

---

📤 Combined Send & Assert (Compact Tests)

1await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .sendAndExpect("post", "/posts", res => {
4    res.thenExpectStatus(201).thenExpectBody("$.title", "foo");
5  }, {
6    headers: { "Content-Type": "application/json" },
7    body: { title: "foo", body: "bar", userId: 1 }
8  });

🛡️ Assertion Wrapper: catchAndLog()

Use catchAndLog() to wrap custom assertions or logic. If it throws, the error will be logged with context.

1const response = await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .whenGet("/posts/1");
4
5response.catchAndLog(() => {
6  const body = response.thenExtract("$.body");
7  if (!body || body.length < 10) {
8    throw new Error("Body is unexpectedly short");
9  }
10});

This is useful for edge-case checks or combining your own logic with the library’s logging system.

---

🧪 Extract and Reuse Response Data

1const post = await fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .givenBody({ title: "foo", body: "bar", userId: 1 })
4  .whenPost("/posts");
5
6const id = post.thenExtract("$.id");
7
8await fluentRest()
9  .setBaseUrl("https://jsonplaceholder.typicode.com")
10  .whenGet(`/posts/${id}`)
11  .thenExpectStatus(200);

🧪 Joi Schema Validation Example

Use Joi to validate the full response body structure:

1import Joi from "joi";
2
3const schema = Joi.object({
4  id: Joi.number().required(),
5  title: Joi.string().required(),
6  body: Joi.string().required(),
7  userId: Joi.number().required()
8});
9
10await fluentRest()
11  .setBaseUrl("https://jsonplaceholder.typicode.com")
12  .whenGet("/posts/1")
13  .thenValidateBody(schema);

---

🔍 Debugging

To inspect the request before sending:

1fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .givenBody({ name: "debug" })
4  .debug();

---

🧩 Request Snapshot Debugging

You can print or retrieve a snapshot of the full request configuration:

1const builder = fluentRest()
2  .setBaseUrl("https://jsonplaceholder.typicode.com")
3  .givenHeader("X-Debug", "true")
4  .givenQueryParam("debug", "1");
5
6builder.debug(); // Console output
7
8const snapshot = builder.getSnapshot();
9console.log("Snapshot method:", snapshot.method);

This is useful for troubleshooting test cases, comparing requests, or snapshot testing.

---

🌐 Proxy Support

🔧 Global Proxy Configuration

Apply a proxy to all requests by default:

1configureDefaults({
2  proxy: {
3    host: 'proxy.example.com',
4    port: 8080,
5    auth: {
6      username: 'user',
7      password: 'pass'
8    }
9  }
10});

---

🚀 Per-Request Proxy Override

Override the global proxy using .setProxy():

1const response = await fluentRest()
2  .setProxy({
3    host: 'custom.proxy.com',
4    port: 3128,
5    auth: {
6      username: 'customUser',
7      password: 'customPass'
8    }
9  })
10  .whenGet('/posts/1');

---

🛑 Disabling Proxy for a Specific Request

Disable proxy even if one is globally configured:

1const response = await fluentRest()
2  .clearProxy()
3  .whenGet('/health');

---

🔁 Proxy Resolution Order

1. setProxy(...) – per-request override
2. configureDefaults(...) – global default
3. No proxy – if .clearProxy() is used

---

📦 Proxy Object Format

The proxy object must match Axios's format:

1{
2  host: string;
3  port: number;
4  auth?: {
5    username: string;
6    password: string;
7  };
8  protocol?: 'http' | 'https';
9}

---

🔍 Utilities and Tools

• configureDefaults() – Global config via code
• .env support – Set RA_TIMEOUT, RA_LOG_LEVEL, etc.
• debug() – Print live config to terminal
• getSnapshot() – Inspect request config object
• thenExtract(path) – Pull specific data from response
• catchAndLog(fn) – Wrap and log assertion errors with context

---

🧱 Designed For

• TypeScript-first testing
• Frameworks like Playwright / Vitest / Jest / Mocha
• CI/CD environments
• Readable and compact API test syntax

---

📦 Dependencies

Package	Purpose
Axios	HTTP client
JSONPath-Plus	JSON extraction from response
Joi	Schema validation
Form-Data	Multipart/form-data support
Chalk	Terminal logging colors

---

📄 License

MIT – Use, extend, and enjoy!

---