Тесты плагинов без сервера
Тест загружает настоящий код плагина — собранный тем же 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
pnpm vitest run
yarn vitest run
bunx 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.3 | id игроков, сквозь которых проходит 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 слышит каждое пользовательское
сообщение, которое отправляет плагин.