@opra/testing 1.26.3 → 1.27.0

package/README.md

@@ -1,3 +1,26 @@
-# @opra/I18n
+# @opra/testing
 
-OPRA i18n package.
+[![NPM Version][npm-image]][npm-url]
+[![NPM Downloads][downloads-image]][downloads-url]
+[![CI Tests][ci-test-image]][ci-test-url]
+[![Test Coverage][coveralls-image]][coveralls-url]
+
+
+## Support
+You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+
+## Node Compatibility
+- node >= 20.x
+
+
+## License
+Available under [MIT](LICENSE) license.
+
+[npm-image]: https://img.shields.io/npm/v/@opra/testing
+[npm-url]: https://npmjs.org/package/@opra/testing
+[downloads-image]: https://img.shields.io/npm/dm/@opra/testing.svg
+[downloads-url]: https://npmjs.org/package/@opra/testing
+[ci-test-image]: https://github.com/panates/opra/actions/workflows/test.yml/badge.svg
+[ci-test-url]: https://github.com/panates/opra/actions/workflows/test.yml
+[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=main
+[coveralls-url]: https://coveralls.io/github/panates/opra?branch=main

package/api-expect/api-expect.d.ts

@@ -4,27 +4,48 @@ import { ApiExpectCollection } from './api-expect-collection.js';
 import { ApiExpectError } from './api-expect-error.js';
 import { ApiExpectObject } from './api-expect-object.js';
 import { ApiExpectOperationResult } from './api-expect-operation-result.js';
+/**
+ * Main entry point for API assertions.
+ *
+ * @class ApiExpect
+ */
 export declare class ApiExpect extends ApiExpectBase {
     /**
-     * Tests if request succeeded
-     * @param status Status code number between 200-299
+     * Asserts that the request was successful (status code 200-399).
+     *
+     * @param status Optional expected status code.
+     * @returns The current ApiExpect instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toSuccess(status?: number): this;
     /**
-     * Tests if request failed
-     * @param status Status code number between 400-599
+     * Asserts that the request failed (status code 400-599).
+     *
+     * @param status Optional expected status code.
+     * @returns An {@link ApiExpectError} instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toFail(status?: number): ApiExpectError;
     /**
-     * Tests if API returns a Collection
+     * Asserts that the API returned a Collection.
+     *
+     * @returns An {@link ApiExpectCollection} instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toReturnCollection(): ApiExpectCollection;
     /**
-     * Tests if API returns an Object
+     * Asserts that the API returned an Object.
+     *
+     * @param contentType Optional expected Content-Type header value.
+     * @returns An {@link ApiExpectObject} instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toReturnObject(contentType?: string): ApiExpectObject;
     /**
-     * Tests if API returns an OperationResult
+     * Asserts that the API returned an OperationResult.
+     *
+     * @returns An {@link ApiExpectOperationResult} instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toReturnOperationResult(): ApiExpectOperationResult;
 }

package/api-expect/api-expect.js

@@ -8,10 +8,18 @@ import { ApiExpectCollection } from './api-expect-collection.js';
 import { ApiExpectError } from './api-expect-error.js';
 import { ApiExpectObject } from './api-expect-object.js';
 import { ApiExpectOperationResult } from './api-expect-operation-result.js';
+/**
+ * Main entry point for API assertions.
+ *
+ * @class ApiExpect
+ */
 export class ApiExpect extends ApiExpectBase {
     /**
-     * Tests if request succeeded
-     * @param status Status code number between 200-299
+     * Asserts that the request was successful (status code 200-399).
+     *
+     * @param status Optional expected status code.
+     * @returns The current ApiExpect instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toSuccess(status) {
         let msg = '';
@@ -53,8 +61,11 @@ export class ApiExpect extends ApiExpectBase {
         return this;
     }
     /**
-     * Tests if request failed
-     * @param status Status code number between 400-599
+     * Asserts that the request failed (status code 400-599).
+     *
+     * @param status Optional expected status code.
+     * @returns An {@link ApiExpectError} instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toFail(status) {
         let msg = '';
@@ -96,7 +107,10 @@ export class ApiExpect extends ApiExpectBase {
         return new ApiExpectError(this.response);
     }
     /**
-     * Tests if API returns a Collection
+     * Asserts that the API returned a Collection.
+     *
+     * @returns An {@link ApiExpectCollection} instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toReturnCollection() {
         let msg = '';
@@ -123,7 +137,11 @@ export class ApiExpect extends ApiExpectBase {
         return new ApiExpectCollection(this.response);
     }
     /**
-     * Tests if API returns an Object
+     * Asserts that the API returned an Object.
+     *
+     * @param contentType Optional expected Content-Type header value.
+     * @returns An {@link ApiExpectObject} instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toReturnObject(contentType) {
         let msg = '';
@@ -149,7 +167,10 @@ export class ApiExpect extends ApiExpectBase {
         return new ApiExpectObject(this.response);
     }
     /**
-     * Tests if API returns an OperationResult
+     * Asserts that the API returned an OperationResult.
+     *
+     * @returns An {@link ApiExpectOperationResult} instance.
+     * @throws {@link Error} if the assertion fails.
      */
     toReturnOperationResult() {
         let msg = '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/testing",
-  "version": "1.26.3",
+  "version": "1.27.0",
   "description": "Opra testing package",
   "author": "Panates",
   "license": "MIT",
@@ -12,8 +12,8 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@opra/client": "^1.26.3",
-    "@opra/common": "^1.26.3",
+    "@opra/client": "^1.27.0",
+    "@opra/common": "^1.27.0",
     "expect": "^29.0.0 || ^30.0.0",
     "jest-matcher-utils": "^29.0.0 || ^30.0.0"
   },

package/test-backend.d.ts

@@ -7,19 +7,43 @@ export type ResponseExt = {
     expect: ApiExpect;
 };
 /**
+ * Test specific implementation of {@link FetchBackend} for API testing.
  *
  * @class TestBackend
  */
 export declare class TestBackend extends FetchBackend {
     protected _server: Server;
+    /**
+     * Creates a new instance of TestBackend.
+     *
+     * @param app The server or request listener to test.
+     * @param options Configuration options.
+     */
     constructor(app: Server | RequestListener, options?: OpraTestClient.Options);
+    /**
+     * Sends the actual HTTP request by starting the server if necessary.
+     *
+     * @param req The request to send.
+     * @returns A promise that resolves to the response.
+     * @protected
+     */
     protected send(req: Request): Promise<Response>;
+    /**
+     * Creates a {@link HttpResponse} instance with an added `expect` property.
+     *
+     * @param init The response initiator parameters.
+     * @returns A new HttpResponse instance with ApiExpect.
+     * @protected
+     */
     protected createResponse(init: HttpResponse.Initiator): HttpResponse<any> & ResponseExt;
 }
 /**
+ * Namespace for {@link TestBackend} related types and interfaces.
+ *
  * @namespace TestBackend
  */
 export declare namespace TestBackend {
+    /** Configuration options for TestBackend */
     interface Options extends FetchBackend.Options {
     }
 }

package/test-backend.js

@@ -3,17 +3,31 @@ import * as path from 'node:path';
 import { FetchBackend, HttpResponse } from '@opra/client';
 import { ApiExpect } from './api-expect/api-expect.js';
 /**
+ * Test specific implementation of {@link FetchBackend} for API testing.
  *
  * @class TestBackend
  */
 export class TestBackend extends FetchBackend {
     _server;
+    /**
+     * Creates a new instance of TestBackend.
+     *
+     * @param app The server or request listener to test.
+     * @param options Configuration options.
+     */
     constructor(app, options) {
         super(options?.basePath
             ? path.posix.join('http://tempuri.org', options.basePath)
             : 'http://tempuri.org', options);
         this._server = app instanceof Server ? app : createServer(app);
     }
+    /**
+     * Sends the actual HTTP request by starting the server if necessary.
+     *
+     * @param req The request to send.
+     * @returns A promise that resolves to the response.
+     * @protected
+     */
     send(req) {
         return new Promise((resolve, reject) => {
             const url = new URL(req.url);
@@ -51,6 +65,13 @@ export class TestBackend extends FetchBackend {
             });
         });
     }
+    /**
+     * Creates a {@link HttpResponse} instance with an added `expect` property.
+     *
+     * @param init The response initiator parameters.
+     * @returns A new HttpResponse instance with ApiExpect.
+     * @protected
+     */
     createResponse(init) {
         const response = new HttpResponse(init);
         response.expect = new ApiExpect(response);

package/test-client.d.ts

@@ -12,8 +12,19 @@ export declare namespace OpraTestClient {
         basePath?: string;
     }
 }
+/**
+ * Test specific implementation of {@link HttpClientBase} for API testing.
+ *
+ * @class OpraTestClient
+ */
 export declare class OpraTestClient extends HttpClientBase<FetchBackend.RequestOptions, ResponseExt> {
     [kBackend]: TestBackend;
+    /**
+     * Creates a new instance of OpraTestClient.
+     *
+     * @param app The server or request listener to test.
+     * @param options Configuration options.
+     */
     constructor(app: Server | RequestListener, options?: OpraTestClient.Options);
 }
 export {};

package/test-client.js

@@ -1,7 +1,18 @@
 import { HttpClientBase } from '@opra/client';
 import { TestBackend } from './test-backend.js';
 export const kContext = Symbol.for('kContext');
+/**
+ * Test specific implementation of {@link HttpClientBase} for API testing.
+ *
+ * @class OpraTestClient
+ */
 export class OpraTestClient extends HttpClientBase {
+    /**
+     * Creates a new instance of OpraTestClient.
+     *
+     * @param app The server or request listener to test.
+     * @param options Configuration options.
+     */
     constructor(app, options) {
         super(new TestBackend(app, options));
     }