Тесты

Тесты плагинов без сервера

Тест загружает настоящий код плагина — собранный тем же AssemblyScript, с тем же API и теми же нативами, что и сборка для сервера, — в поддельный сервер на TypeScript и управляет им так, как это делали бы игроки и игра. Библиотека — @amxts/core/test-utils, она входит в ядро:

import { 
expect
,
test
} from "bun:test";
import {
setup
} from "@amxts/core/test-utils";
test
("/hp лечит раненого игрока", async () => {
const
server
= await
setup
(); // проект: его модули, затем его плагины
const
player
=
server
.
join
("Alice", {
team
: "CT",
health
: 40 });
player
.
say
("/hp");
expect
(
player
.
chat
).toContain("Alice, your HP: 40");
expect
(
player
.
health
).toBe(100);
}, 60_000); // первый тест собирает плагины

Тесты работают под любым тестовым раннером с test и expect как в Jest. С bun test импортируйте их из bun:test, как выше:

bun test

С Vitest, на Node, импортируйте их из vitest:

import { 
expect
,
test
} from "vitest";
import {
setup
} from "@amxts/core/test-utils";
npx vitest run

npx amxts test запускает их раннером проекта — Vitest, когда в проекте установлен vitest, иначе bun test — и передаёт ему опции как есть. Проект, созданный через npm create amxts, пишет тесты под выбранный менеджер пакетов: bun:test с Bun, Vitest с npm, pnpm или Yarn.

Плагин собирается один раз за прогон, а каждый setup() получает свои экземпляры, так что тесты не делят состояние.

Собранное хранится в node_modules/.cache/amxts папки, из которой запущены тесты, и следующий прогон не собирает его заново: плагин собирается снова, только когда меняется он сам, файл, который он импортирует, amxts.config.ts проекта или версия amxts. AMXTS_TEST_CACHE=0 это отключает; удаление папки очищает кеш.

Поддельный сервер — заменитель: он отвечает так, как AMX Mod X и модуль amxts, но это не игровой сервер. Он выполняет верхний уровень плагина, затем init, затем pluginsLoaded, затем configsExecuted — в серверном порядке.

Натив, на который фейковый сервер не отвечает, останавливает тест с его именем: the plugin called the native "get_user_time", which the fake server does not simulate. Фейковый сервер отвечает на нативы, которыми пользуются @amxts/core и официальные модули; модуль, которому нужно больше, приносит их в своём тестовом наборе, а тест может ответить на натив сам через server.defineNative(name, native).

Проект: setup()

setup() ставит проект на новый поддельный сервер так, как amxts build раскладывает его на настоящем: модули из его amxts.config.ts, которыми пользуются его плагины (или которые оставляет pawn), — каждый после тех, что ему нужны, и со своим тестовым набором, — затем его плагины, затем начинается карта.

const 
server
= await setup(); // папка, из которой запущены тесты
const
server
= await setup({
rootDir
: "playground" }); // другой проект
const
server
= await setup({
plugins
: ["welcome"] }); // только некоторые плагины, в этом порядке
const
server
= await setup({
start
: false }); // загрузить, но карту пока не начинать
const
server
= await setup({
maxPlayers
: 10,
cvars
: {
mp_freezetime
: "0" } }); // настройки сервера, ниже

Собственная папка модуля, где нет amxts.config.ts, — это модуль один (и модули, которые ему нужны) со своими значениями по умолчанию.

Один плагин: loadPlugin()

import { 
loadPlugin
} from "@amxts/core/test-utils";
const
server
= await
loadPlugin
("plugins/hello.ts");
const
both
= await
loadPlugin
(["plugins/a.ts", "plugins/b.ts"]);

loadPlugin загружает в новый сервер только те плагины, что ему дали, и начинает карту. new FakeServer(options) и server.load("plugins/a.ts") делают то же по шагам; пакет модуля загружается по имени — server.load("@you/greeter"). await server.reload(server.plugins[0]) с v0.3 — это amxts_reload этого плагина: он слышит "end", его файл загружается снова, и новый плагин слышит старт карты; его метод и возвращает.

Сервер

const 
server
= await setup({
map
: "de_inferno", // "de_dust2"
maxPlayers
: 20, // 32
modules
: ["cstrike", "fun"], // что находит hasModule(); по умолчанию все
cvars
: {
mp_freezetime
: "5" }, // до загрузки плагина
files
: { "addons/amxmodx/configs/myplugin.ini": "speed = 250" }, // папка игры
platform
: "win32", // что скажет platform(); "linux"
timeZone
: "Asia/Yerevan", // пояс сервера для местных геттеров Date; этой машины
env
: {
MYPLUGIN_TOKEN
: "test" }, // окружение сервера для env(); пустое
frameTime
: 10, // мс между кадрами в advance(); 10 (100 fps)
});

У сервера есть квары игры mp_freezetime (6) и mp_round_infinite (0) с v0.3 и квары AMX Mod X amx_language (en) и amx_client_languages (1) — с этими значениями, если cvars не задаёт другие.

modules без "reapi" — сервер без ReAPI, как обычный HLDS: события игры об игроке приходят через Ham Sandwich (server.fireHam), а событие, которое есть только у ReGameDLL, — через хук, которым его там слышно: сообщение (server.sendMessage), строку лога игры (server.gameLog('World triggered "Round_End"')), форвард fakemeta (server.fireForward("FM_EmitSound", [...])), — а где его никто не слышит, обработчика нет.

Плагины на одном сервере слышат форварды и нативы друг друга, как на настоящем.

server.join(name, options)игрок заходит: client_connect, client_authorized, client_putinserver
server.advance(ms)двигает часы и по порядку запускает все таймеры, чей срок подошёл, стреляя событие "frame" каждые frameTime миллисекунд по пути, как сервер с v0.3.5
await server.responses()ждёт веб-запросы, которые плагины отправили через fetch и useFetch, их запросы через Database и работу, отданную рабочему потоку (fs.extract, zlib.gzip с v0.3.1), и отдаёт каждый ответ его плагину, как это сделал бы следующий кадр; см. ниже
server.fire(name, ...args)поднимает форвард — "plugin_cfg", "client_command", "my_on_round_end" — для обработчиков и для Forward.subscribe()
server.fireHook(event, args, { result })прогоняет хукчейн; см. ниже
server.runCommand(player, command) с v0.3.3команда движения игрока — { forward, side, up, msec, buttons, impulse, angles }, кнопки битами (IN_JUMP — 2) — приходит на сервер: "impulse", если в ней он есть, затем "cmdStart", слушатели которого её читают и меняют; возвращает команду после них. bot.move бота тоже её выполняет
server.sendVisibility(player, origin) с v0.3.3сервер выбирает сущности, которые отправит player, — слушатели "visibility" получают origin, без него — origin самого игрока; возвращает все точки, из которых ему отправляют видимое, — сначала ту, что они оставили, затем добавленные
server.sendMessage(name, args, { player, types })шлёт клиенту сообщение, как игра, — по имени у игры и с аргументами в её порядке ("DeathMsg" у "death"): слушатели сообщений читают и меняют его; возвращает { prevented, args, recipients }, recipients — id игроков, которых выбрал слушатель, или null
server.sendTempEntity(args, { source, player, types }) с v0.3.3шлёт временный эффект, как игра, — args начинаются с его номера TE_* — всем игрокам или только player: слушатели tempEntity слышат его с source (сущность или игрок) в event.source; возвращает { prevented, args, players }, players — id игроков, которые его получили
server.fireHam(event, entity, args, { result })прогоняет функцию сущности через слушателей её класса; см. ниже
server.hooked(event, { post, classname })доходит ли событие игры до плагинов: false, когда снят его последний обработчик, undefined, если его никто не слушал; classname спрашивает о хуке Ham Sandwich для этого класса
server.hamCallsфункции сущностей, которые выполнили плагины, — weapon.deploy() и прочие — по порядку: { fn, entity, args, hooks }
server.native(name, ...args)вызывает натив плагина из export function так, как Pawn, — текст, Float, массивы, буфер для результата — и отдаёт то, что прочитал бы Pawn: текст, массив, число
server.amxtsNative(name, ...args)вызывает собственный натив модуля для Pawn — семейство amxts_*_player_data* — так, как Pawn-плагин; server.playerData — само хранилище
server.nativeWithRoom(name, room, args)то же с буфером результата на room ячеек (charsmax(out) или size массива)
server.writeFile(path, text) / server.file(path)папка игры, которую видят fs и файловые нативы, — в памяти
server.setCvar(name, value) / server.cvar(name)квар, как его ставит консоль; слушатели изменения его слышат
server.env с v0.3окружение сервера; env() читает его поверх файла addons/amxts/.env (положите его в files). Плагин, которому нужна переменная, которой нет ни там, ни там или которая не того вида, не загружается: setup и server.load бросают строку модуля, [amxts] myplugin needs MYPLUGIN_TOKEN in addons/amxts/.env
server.translate(lines, language)строки словаря, как их пишет файл, по умолчанию "en": server.translate({ MYPLUGIN_HELLO: "Hello, %s" }); файл в addons/amxmodx/data/lang читается, когда плагин его загружает. Язык игрока — его setinfo lang: alice.info.set("lang", "ru")
server.storage(name)значения хранилища Storage по ключу как Map — заполните его до того, как плагин прочитает. Его keys() — итератор Map: [...server.storage("myplugin").keys()] — тот же массив, что storage.keys() в плагине
server.logчто написали console.log и server_print, строка за строкой
server.serverCommand(line)строка, набранная в консоли сервера и разбитая так, как её разбивает движок: её обработчики server.addServerCommand; true, если один из них её забрал
server.commandsчто выполнил server.command()
server.forwardsотправленные форварды, { name, args }
server.players, server.player(id)кто подключён
server.timeмиллисекунды с начала карты
server.roundEndsраунды, которые плагин закончил (game.endRound, rg_round_end): { status, event, delay, message, sound, trigger }
server.soundsсыгранные звуки: entity.emitSound от сущности, player.playSound одному игроку — { entity, sample }
server.userMessagesотправленные пользовательские сообщения (player.screen.*, UserMessage с v0.3.3 по его имени, message_begin ... message_end) по порядку: { name, player, args } — args это значения write_*, строка — текстом: { name: "ScreenFade", player: 1, args: [2048, 0, 0, 200, 0, 0, 100] }; эффект (effects.*) — это "SVC_TEMPENTITY", другое сообщение движка — своё имя SVC_ ("SVC_NEWMOVEVARS"), с dest — 0 все, 4 рядом с точкой, 8 один игрок — и origin
server.playerMove с v0.3движение игрока, которое читает событие движения; задаётся перед fireHook: server.playerMove.touchCount = 2 — это event.touchCount, frameTime — event.frameTime
server.walksThrough(id) с v0.3.3, server.walkThroughLook с v0.3.3id игроков, сквозь которых проходит id, как их задал модуль через walksThrough из kit (см. проход сквозь друг друга); вид, который задал модуль, { fadeDistance, opacity, hideDistance }
server.walkThroughOptions с v0.3.5что ещё проходит сквозь партнёра, как это задал модуль через setWalkThroughOptions из kit: { grenades, standOnHead }
server.semiclipMasks, server.semiclipControlledмаска модуля ReSemiclip каждого игрока (resemiclip_set_user_mask); забраны ли его правила (resemiclip_take_control)
server.bartimes, server.rules, server.precachedполоска прогресса у каждого игрока; члены game rules, которые записал плагин; что взял server.precache в событии "precache", которое сервер поднимает до "init"
server.touch(toucher, touched)одна сущность входит в другую: обработчики "touch", чьи классы подходят; ответ 1, если один из них касание заблокировал
server.answerCvar(player, cvar, value)ответ клиента на player.queryCvar (или query_client_cvar)

Плагин, который ждёт — async-функция, sleep, промис, — работает здесь как на сервере, так что sleep(1000) продолжается, когда server.advance() его проходит.

Веб-запрос, который плагин отправляет через fetch или useFetch, уходит по-настоящему, с машины, на которой идут тесты, а его ответ доходит до плагина на await server.responses(). Направляйте плагин на веб-сервер, который тест запускает сам (Bun.serve), а не в интернет:

const 
web
= Bun.serve({
port
: 0,
fetch
: () => Response.json({
temperature
: 21 }) });
const
server
= await setup();
server
.setCvar("myplugin_weather_url", `http://127.0.0.1:${
web
.port}`);
const
alice
=
server
.join("Alice");
alice
.say("/weather");
await
server
.responses();
expect(
alice
.chat).toContain("21 °C");
web
.stop();

request модуля по адресу ftp:, ftps: или sftp: уходит так же, через пакеты basic-ftp и ssh2-sftp-client — поставьте их рядом с тестами (npm install -D basic-ftp ssh2-sftp-client). Сервер тест запускает в своём процессе — ftp-srv для FTP и FTPS, ssh2 для SFTP, — а file запроса — файл из server.files.

Запрос Database с v0.3.1 никуда не уходит: на него отвечает тест. server.database(url) — база по адресу (по любому адресу, если url не задан), а ответ плагин получает на await server.responses():

const 
server
= await setup({
env
: {
MYPLUGIN_DB
: "mysql://myplugin:secret@127.0.0.1/myplugin" } });
const
db
=
server
.database("mysql://myplugin:secret@127.0.0.1/myplugin");
db
.answer("SELECT name, time FROM records WHERE map = ? ORDER BY time LIMIT 10", [{
name
: "Alice",
time
: 61.2 }]);
db
.answer(/^INSERT INTO records/, {
insertId
: 7,
affectedRows
: 1 });
db
.fail(/^DELETE/, {
code
: 1142,
sqlState
: "42000",
message
: "DELETE command denied" });
const
alice
=
server
.join("Alice");
alice
.say("/top");
await
server
.responses();
expect(
alice
.chat).toContain("1. Alice 61.20");
expect(
db
.queries.at(-1)).toEqual({
sql
: "SELECT name, time FROM records WHERE map = ? ORDER BY time LIMIT 10",
params
: ["de_dust2"],
transaction
: 0 });
answer(sql, result)отвечает на запрос — его SQL как написан, без учёта пробелов, или шаблон — строками, { insertId, affectedRows } или функцией от его значений, которая даёт одно из них; для запроса берётся последний заданный ответ
fail(sql, { code, sqlState, message })запрос завершается ошибкой, как его отклонил бы сервер; без code — как оборванное соединение
queriesвсе запросы плагинов: { sql, params, transaction }
transactionsвсе транзакции: { id, queries, committed }, committed — true, false при откате, null, пока идёт

Запрос, на который никто не ответил, останавливает тест на server.responses() с его SQL.

Uint8Array в строке — байты бинарной колонки, а байты, которые отправил плагин, — Uint8Array в params.

Игроки

import { 
setup
} from "@amxts/core/test-utils";
const
server
= await
setup
();
const
alice
=
server
.
join
("Alice", {
team
: "CT", // "CT"
health
: 100,
armor
: 0,
alive
: true,
bot
: false,
steamId
: "STEAM_0:0:42", // STEAM_0:0:<id>, у бота BOT
flags
: "abcu", // буквы users.ini; "z"
origin
: [0, 0, 0],
weapons
: ["weapon_knife", "weapon_usp"], // первое - в руках; нож
});
alice
.
say
("/hp"); // true, если плагин его забрал
alice
.
sayTeam
("rush b");
alice
.
command
("amx_slap \"Bob\" 5"); // консольная команда, разбитая как это делает движок
alice
.
disconnect
({
dropped
: true,
reason
: "Kicked" });

Что ему показали, строка за строкой, без байтов цвета: alice.chat, alice.center, alice.console, alice.hud; все строки по порядку — в alice.messages, а alice.clearMessages() начинает заново. Строка чата, которую не забрал ни один плагин, попадает в чат всем как Alice: text. alice.chatRaw с v0.3 — чат таким, каким его получил клиент, с кодами цвета \x01-\x04: player.print("KZ !gGG") приходит как "\x01KZ \x04GG".

Его состояние: health, armor, frags, deaths, team, alive, origin, muted, items и activeItem (оружие с полем kind), ammo (по имени оружия), commands (что client_cmd выполнил в его консоли).

Сущности

Игрок и оружие — сущности, как и всё, что создаёт create_entity, — server.createEntity("info_target"). Любое поле entvar или member читается и пишется по имени, с префиксом или без; дробное — число, вектор — массив из трёх:

alice.get("gravity");          // 0.5
alice.set("renderfx", 19);
alice.get("rendercolor");      // [0, 160, 255]
alice.get("m_iHideHUD");       // 32

Хукчейны

fireHook прогоняет цепочку так, как её прогнала бы игра: pre-слушатели, собственная функция игры, если её никто не остановил, затем post-слушатели.

import { 
constant
,
setup
} from "@amxts/core/test-utils";
const
server
= await
setup
();
const
attacker
=
server
.
join
("Alice", {
team
: "CT" });
const
victim
=
server
.
join
("Bob", {
team
: "CT" });
const
hit
=
server
.
fireHook
("takeDamage", [
victim
.
id
, 0,
attacker
.
id
, 30.0,
constant
("DMG_BULLET")], {
result
: 1 });
hit
.
prevented
; // pre-слушатель вызвал preventDefault() или ответил
hit
.
result
; // ответ цепочки после всех слушателей
hit
.
args
; // аргументы, какими их оставили слушатели (event.damage = ...)
server
.
fireHook
("fallDamage", [
victim
.
id
], {
result
: 40 }).
result
; // 20 с post-слушателем, делящим пополам

Событие называется так же, как в game.addEventListener, или коротким именем ReAPI ("take_damage"). Аргументы — собственные аргументы цепочки по порядку; дробный пишется числом. result — что отвечает функция игры, когда она выполняется, — то, что post-слушатель читает как event.result. Ответ возвращается в типе цепочки: число, boolean или текст.

fireHam делает то же для события, которое слушают на одном классе сущностей ({ classname }): сущность идёт первой, её класс выбирает слушателей.

const 
knife
=
server
.createEntity("weapon_knife");
server
.fireHam("primaryAttack",
knife
).prevented; // true, если слушатель его заблокировал
server
.fireHam("takeDamage", box, [0, attacker.id, 30.0, 2], {
result
: 1 }); // урон разбиваемому объекту

Таймеры

setTimeout и setInterval идут только по поддельным часам: server.advance(45_000) запускает 45-секундный интервал один раз, advance(90_000) — два, а clearTimeout до этого — ни разу.

advance стреляет событие "frame" каждые frameTime миллисекунд (10 по умолчанию, 100 fps) с v0.3.5, чередуя с таймерами, как сервер стреляет server_frame каждый тик. Слушатель "frame" плагина работает во время advance без отдельного server.fire("server_frame").

game.time, performance.now() и Date.now() — те же самые часы: advance двигает их вместе, а команда игрока видит game.time сервера, а не собственные часы, как на настоящем сервере.

Тестовый набор модуля

Модуль, чей плагин вызывает нативы, на которые поддельный сервер не отвечает, — show_menu у модуля меню, вызовы Pawn-плагинов в ответ, — поставляет тестовый набор: файл, который называет его package.json, чей экспорт по умолчанию добавляет нужное модулю в каждый поддельный сервер, где он работает.

"amxts": {
  "module": "src/index.ts",
  "testing": "testing/index.ts"
},
"exports": {
  ".": "./src/index.ts",
  "./testing": "./testing/index.ts"
}
// testing/index.ts
import type { FakePlayer, FakeServer } from "@amxts/core/test-utils";
import { 
defineTestKit
} from "@amxts/core/test-utils";
const
shown
= new
WeakMap
<FakeServer, Map<number, string>>();
export default
defineTestKit
({
install
(
server
) {
const
screens
= new
Map
<number, string>();
shown
.
set
(
server
,
screens
);
server
.
defineNative
("show_menu", (
call
, [
id
,
_keys
,
text
]) => {
screens
.
set
(
id
,
call
.
memory
.
text
(
text
));
return 1; }); }, }); /** Что показывает меню игрока на этом сервере. */ export function screenOf(
server
: FakeServer,
player
: FakePlayer) {
return
shown
.
get
(
server
)?.
get
(
player
.
id
) ?? null;
}

Набор ставится до того, как загрузится плагин модуля: это делают setup() и server.load("@you/menus"). Тест импортирует то, что набор даёт, из пакета — import { screenOf } from "@you/menus/testing". server.defineNative(name, native) отвечает на натив на этом сервере; натив получает вызов — call.memory читает память плагина, call.plugin — кто вызвал, — и ячейки, которые положил Pawn. server.messageListeners слышит каждое пользовательское сообщение, которое отправляет плагин.