Skip to content

Commit 3e948b2

Browse files
stazzstazz
committed
#6 The 'server-test-support' is now documented.
1 parent 39b8892 commit 3e948b2

File tree

8 files changed

+141
-41
lines changed

8 files changed

+141
-41
lines changed

‎.github/workflows/build-and-test.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ jobs:
4040
- endpoint-prefix
4141
- endpoint-spec
4242
- server
43-
# - server-test-support
43+
- server-test-support
4444
runs-on: ubuntu-latest
4545
name: Build and test ${{ matrix.dir }}
4646
steps:

‎server-test-support/package.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@ty-ras/server-test-support",
3-
"version": "0.13.0",
3+
"version": "1.0.0",
44
"author": {
55
"name": "Stanislav Muhametsin",
66
"email": "[email protected]",
@@ -31,7 +31,7 @@
3131
}
3232
},
3333
"dependencies": {
34-
"@ty-ras/server": "0.13.0",
34+
"@ty-ras/server": "^1.0.0",
3535
"@ava/get-port": "2.0.0",
3636
"raw-body": "2.5.1"
3737
},

‎server-test-support/src/destroy.ts

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,15 @@
1-
import * as net from "net";
2-
import * as crypto from "crypto";
3-
import type * as stream from "stream";
1+
/**
2+
* @file This file contains code for creating callback to destroy a {@link net.Server}.
3+
*/
4+
import * as net from "node:net";
5+
import * as crypto from "node:crypto";
6+
import type * as stream from "node:stream";
47

8+
/**
9+
* Creates a callback to destroy the given {@link net.Server}.
10+
* @param server The {@link net.Server} to destroy when calling the returned callback.
11+
* @returns A callback to destroy the given server.
12+
*/
513
export const createDestroyCallback = (server: net.Server) => {
614
const connections: Record<string, net.Socket | stream.Duplex> = {};
715

‎server-test-support/src/index.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file This is entrypoint file for this package, exporting all non-internal files.
3+
*/
4+
15
export * from "./test";
26
export * from "./server";
37
export * from "./destroy";

‎server-test-support/src/request.ts

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,19 @@
1-
import * as http from "http";
2-
import * as https from "https";
3-
import * as http2 from "http2";
4-
import type * as stream from "stream";
1+
/**
2+
* @file This file contains code to sending a HTTP request asynchronously.
3+
*/
54

5+
import * as http from "node:http";
6+
import * as https from "node:https";
7+
import * as http2 from "node:http2";
8+
import type * as stream from "node:stream";
9+
10+
/**
11+
* Asynchronously sends HTTP1 request, returning response headers and data.
12+
* @param opts The HTTP1 request options.
13+
* @param write The optional callback to write to request body.
14+
* @returns The returned HTTP1 response headers and data.
15+
* @throws The {@link RequestError} if returned response doesn't have status code or it is `>= 400`.
16+
*/
617
export const requestAsync = (
718
opts: http.RequestOptions,
819
write?: (writeable: stream.Writable) => Promise<void>,
@@ -55,6 +66,13 @@ export const requestAsync = (
5566
}
5667
});
5768

69+
/**
70+
* Asynchronously sends HTTP2 request, returning response headers and data.
71+
* @param opts The HTTP2 request options.
72+
* @param write The optional callback to write to request body.
73+
* @returns The returned HTTP2 response headers and data.
74+
* @throws The {@link RequestError} if returned response doesn't have status code or it is `>= 400`.
75+
*/
5876
export const requestAsync2 = (
5977
opts: http.RequestOptions,
6078
write?: (writeable: stream.Writable) => Promise<void>,
@@ -136,7 +154,15 @@ const awaitAndThen = async (
136154
}
137155
};
138156

157+
/**
158+
* This error is thrown when returned HTTP response has no status code, or it is `>= 400`.
159+
*/
139160
export class RequestError extends Error {
161+
/**
162+
* Creates new instance of this error with given data.
163+
* @param statusCode The status code of the HTTP response.
164+
* @param message The mesage.
165+
*/
140166
public constructor(
141167
public readonly statusCode: number | undefined,
142168
message: string,
@@ -145,5 +171,10 @@ export class RequestError extends Error {
145171
}
146172
}
147173

174+
/**
175+
* Creates textual message about status code.
176+
* @param statusCode The status code returned.
177+
* @returns The textual message about status code.
178+
*/
148179
export const getErrorMessage = (statusCode: number | undefined) =>
149180
`Status code: ${statusCode}`;

‎server-test-support/src/server.ts

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file This file contains code related to running tests on specific TyRAS HTTP server implementation.
3+
*/
4+
15
import type * as ava from "ava";
26
import getPort from "@ava/get-port";
37

@@ -7,12 +11,18 @@ import * as request from "./request";
711
import type * as ep from "@ty-ras/endpoint";
812
import * as serverUtils from "@ty-ras/server";
913

10-
import * as http from "http";
11-
import * as http2 from "http2";
12-
import * as https from "https";
13-
import * as stream from "stream";
14+
import * as http from "node:http";
15+
import * as http2 from "node:http2";
16+
import * as https from "node:https";
17+
import * as stream from "node:stream";
1418
import * as rawBody from "raw-body";
1519

20+
/**
21+
* Tests the TyRAS server implementation against ready-made test suite.
22+
* @param t The {@link ava.ExecutionContext} to use.
23+
* @param createServer The callback to create HTTP server.
24+
* @param infos Some information about tests.
25+
*/
1626
export const testServer = async (
1727
t: ava.ExecutionContext,
1828
createServer: (
@@ -98,8 +108,8 @@ const getAppEndpoint = (
98108
getRegExpAndHandler: () => ({
99109
url: regExp,
100110
handler: () => {
101-
const retVal: ep.StaticAppEndpointHandler<unknown, unknown> = {
102-
stateValidator: {
111+
const retVal: ep.AppEndpointHandler<unknown, unknown> = {
112+
stateInformation: {
103113
stateInfo: undefined,
104114
validator: (ctx) =>
105115
protocolError === undefined
@@ -223,6 +233,9 @@ const writeInput = (writable: stream.Writable) => {
223233
return Promise.resolve();
224234
};
225235

236+
/**
237+
* This type represents any HTTP server (1 or 2).
238+
*/
226239
export type AnyHttpServer =
227240
| http.Server
228241
| https.Server
@@ -236,6 +249,10 @@ export type AnyHttpServer =
236249
customListen?: (host: string, port: number) => Promise<void>;
237250
};
238251

252+
/**
253+
* Additional information about test suite.
254+
* Need to remember specifics later, this is cryptic at this point already. :)
255+
*/
239256
export type ServerTestAdditionalInfo = [
240257
(
241258
| undefined

‎server-test-support/src/test.ts

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,18 @@
1+
/**
2+
* @file This file contains code used to register a collection of tests to AVA runner.
3+
*/
4+
15
import type * as ava from "ava";
26
import type * as ep from "@ty-ras/endpoint";
37

48
import * as server from "./server";
59

10+
/**
11+
* Registers a bunch of tests to run against given TyRAS HTTP server implementation using AVA runtime.
12+
* @param test The AVA test runtime.
13+
* @param createServer The callback to create HTTP server.
14+
* @param opts The {@link RegisterTestsOptions}.
15+
*/
616
export const registerTests = (
717
test: ava.TestFn,
818
createServer: CreateServer,
@@ -32,16 +42,37 @@ export const registerTests = (
3242
}
3343
};
3444

45+
/**
46+
* The options for {@link registerTests}.
47+
*/
3548
export type RegisterTestsOptions = Partial<
3649
Omit<TestsInput, "createServer"> & {
3750
run500Test: boolean; // Only makes sense when there are extra code other than invoking typicalServerFlow.
3851
}
3952
>;
4053

54+
/**
55+
* This interface contains necessary data to register tests via {@link registerTests}.
56+
*/
4157
export interface TestsInput {
58+
/**
59+
* The callback to create the TyRAS HTTP server.
60+
*/
4261
createServer: CreateServer;
62+
63+
/**
64+
* The suffix for content types.
65+
*/
4366
contentTypeHeaderSuffix?: string | undefined;
67+
68+
/**
69+
* The HTTP protocol version.
70+
*/
4471
httpVersion: number;
72+
73+
/**
74+
* Whether the server is secure.
75+
*/
4576
secure: boolean;
4677
}
4778

@@ -72,6 +103,9 @@ const test500: ParametrizedTest = async (...args) => {
72103
await testServer(...args, 500);
73104
};
74105

106+
/**
107+
* Callback to create TyRAS HTTP server.
108+
*/
75109
export type CreateServer = (
76110
endpoints: ReadonlyArray<ep.AppEndpoint<unknown, unknown>>,
77111
info: server.ServerTestAdditionalInfo[0],
@@ -91,9 +125,15 @@ const testServer = (
91125
contentTypeHeaderSuffix,
92126
);
93127

128+
/**
129+
* The callback type for parametrized type.
130+
*/
94131
export type ParametrizedTest = (
95132
t: ava.ExecutionContext,
96133
input: TestsInput,
97134
) => Promise<void>;
98135

136+
/**
137+
* The base constraint type for HTTP version.
138+
*/
99139
export type HTTPVersionBase = 1 | 2;

‎server-test-support/yarn.lock

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -389,31 +389,31 @@
389389
resolved "https://registry.yarnpkg.com/@tsconfig/node16/-/node16-1.0.4.tgz#0b92dcc0cc1c81f6f306a381f28e31b1a56536e9"
390390
integrity sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==
391391

392-
"@ty-ras/data-backend@0.13.0":
393-
version "0.13.0"
394-
resolved "https://registry.yarnpkg.com/@ty-ras/data-backend/-/data-backend-0.13.0.tgz#dc45ad57107474cd1b663711fce473c4202df120"
395-
integrity sha512-kn0OZe9Ns01DIhFl4dJniXuKryZNPYZXI2IDL/LQc0vmHsYrwYqNrUuDcUsinR3nweh0sZxyzKhbpvUil49tmw==
392+
"@ty-ras/data-backend@^1.0.1":
393+
version "1.0.1"
394+
resolved "https://registry.yarnpkg.com/@ty-ras/data-backend/-/data-backend-1.0.1.tgz#aa98d3e3d60492bcaf5c9d62aec105e1713cd22c"
395+
integrity sha512-gtknc6LXa2D8h+KymKsS1PDLYmPot6JG7eldGb5koZAgJkayu4hyTULRWQ3Oaf4r940sYvc8+TnyzzpleA9tWg==
396396
dependencies:
397-
"@ty-ras/data" "0.13.0"
397+
"@ty-ras/data" "^1.0.0"
398398

399-
"@ty-ras/data@0.13.0":
400-
version "0.13.0"
401-
resolved "https://registry.yarnpkg.com/@ty-ras/data/-/data-0.13.0.tgz#45acb046958350de01916f2cb433ec9da165abef"
402-
integrity sha512-AZYCdMiBPTO4+V0Apg+i9XUo17c4C5Up+0O8Jk8cBYVCm/4W5kbzGdcE40GKNFqkn71IVrfjv5GAaMpg5EbFXg==
399+
"@ty-ras/data@^1.0.0":
400+
version "1.0.0"
401+
resolved "https://registry.yarnpkg.com/@ty-ras/data/-/data-1.0.0.tgz#d49c7ccba3e26463d05470ff10bb947f8f3293d7"
402+
integrity sha512-WjiVqThVwVX6NpkU3sweiG1I2b6hiIt4VuvbSGWwniAXBJVZg6AFrndOtCgf6MQmmgS/LqOtmT1xbeF/Gk1Ayg==
403403

404-
"@ty-ras/endpoint@0.13.1":
405-
version "0.13.1"
406-
resolved "https://registry.yarnpkg.com/@ty-ras/endpoint/-/endpoint-0.13.1.tgz#a4d5be645444326be799d48d78f7e2f11b139685"
407-
integrity sha512-cAZXA8bZCVth+1HGxrkgrgHieLVXJ+gYaydKKKFhHpfbKqxuwgI7ECxFGRe7m1shTlGBXDvwhD58pMvjy98kyg==
404+
"@ty-ras/endpoint@^1.0.1":
405+
version "1.0.1"
406+
resolved "https://registry.yarnpkg.com/@ty-ras/endpoint/-/endpoint-1.0.1.tgz#5c190b735bbab3dcfb21363d3cefbf8ebcd0ceb0"
407+
integrity sha512-J8jqQpLWR2BhnaMPja3rnO1EkMWqSThRRARrzk/QL/Pv6nwBkLEkHMxoJIyu8hC+bGbL+SKz5WyLFyVwywIOVA==
408408
dependencies:
409-
"@ty-ras/data-backend" "0.13.0"
409+
"@ty-ras/data-backend" "^1.0.1"
410410

411-
"@ty-ras/server@0.13.0":
412-
version "0.13.0"
413-
resolved "https://registry.yarnpkg.com/@ty-ras/server/-/server-0.13.0.tgz#d8eba2ef8ceee1cf6c8724044e08aa87d47b9e3a"
414-
integrity sha512-PgcD+cHyh+M31+zcoSidt5u3lQYsPW4WcnZ9Xpp72VeKS0J2ccgrZn9cN7i7s8gG9b+jaY5r2ZmA5jYfDqAKjw==
411+
"@ty-ras/server@^1.0.0":
412+
version "1.0.0"
413+
resolved "https://registry.yarnpkg.com/@ty-ras/server/-/server-1.0.0.tgz#84c5f54accc02da62744590356bc79f948fa3aa2"
414+
integrity sha512-h1Ss92jIIJn3wwVEP0L2oMT/EYrm9UvDft5YJ9WHMhDZBTXX4EZwTgG7WE//lD4tHHTUvUvhQCpK0BUprAxO+Q==
415415
dependencies:
416-
"@ty-ras/endpoint" "0.13.1"
416+
"@ty-ras/endpoint" "^1.0.1"
417417

418418
"@types/istanbul-lib-coverage@^2.0.1":
419419
version "2.0.4"
@@ -1011,9 +1011,9 @@ eastasianwidth@^0.2.0:
10111011
integrity sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==
10121012

10131013
electron-to-chromium@^1.4.284:
1014-
version "1.4.404"
1015-
resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.4.404.tgz#16baf653a7a2613e221da61480ad02fe84e40231"
1016-
integrity sha512-te57sWvQdpxmyd1GiswaodKdXdPgn9cN4ht8JlNa04QgtrfnUdWEo1261rY2vaC6TKaiHn0E7QerJWPKFCvMVw==
1014+
version "1.4.405"
1015+
resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.4.405.tgz#487bdba2d82a59b092d6b6e4602bf733cec6a7ef"
1016+
integrity sha512-JdDgnwU69FMZURoesf9gNOej2Cms1XJFfLk24y1IBtnAdhTcJY/mXnokmpmxHN59PcykBP4bgUU98vLY44Lhuw==
10171017

10181018
emittery@^1.0.1:
10191019
version "1.0.1"
@@ -1772,9 +1772,9 @@ never@^1.0.3:
17721772
integrity sha512-K0xfZVKUX7hrmbZKmyD1KB+PT8I9b9Ffxvmht8FhRjMIoe7/XyTfgyQko7G6RKvfnT9oxCrq0CARm1De5uXEbQ==
17731773

17741774
node-releases@^2.0.8:
1775-
version "2.0.11"
1776-
resolved "https://registry.yarnpkg.com/node-releases/-/node-releases-2.0.11.tgz#59d7cef999d13f908e43b5a70001cf3129542f0f"
1777-
integrity sha512-+M0PwXeU80kRohZ3aT4J/OnR+l9/KD2nVLNNoRgFtnf+umQVFdGBAO2N8+nCnEi0xlh/Wk3zOGC+vNNx+uM79Q==
1775+
version "2.0.12"
1776+
resolved "https://registry.yarnpkg.com/node-releases/-/node-releases-2.0.12.tgz#35627cc224a23bfb06fb3380f2b3afaaa7eb1039"
1777+
integrity sha512-QzsYKWhXTWx8h1kIvqfnC++o0pEmpRQA/aenALsL2F4pqNVr7YzcdMlDij5WBnwftRbJCNJL/O7zdKaxKPHqgQ==
17781778

17791779
nofilter@^3.1.0:
17801780
version "3.1.0"

0 commit comments

Comments
 (0)