@specter-automation/test 1.0.128 → 1.0.130

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -388,6 +388,25 @@ export declare class SpecterWorld {
388
388
  * Returns the base SpecterLocator, as these objects lack spatial or UI properties.
389
389
  */
390
390
  uobject(className: string): SpecterLocator;
391
+ /**
392
+ * Pauses the test and opens the in-game inspector, the way `page.pause()` opens Playwright's inspector.
393
+ *
394
+ * The game stays exactly as the test left it. Click actors or widgets in the game view to get locators
395
+ * for them, checked against the live game, along with their tags, attributes and components. The test
396
+ * carries on when you close the inspector. Its timeout is switched off while you look around.
397
+ *
398
+ * For writing and debugging tests on your own machine: it does nothing on CI.
399
+ *
400
+ * ```ts
401
+ * const steel = await server.heroes.steel.spawn({ ... });
402
+ * await world.inspect(); // look around, copy a locator, close the inspector to continue
403
+ * ```
404
+ *
405
+ * @param options.mode What to pick first: `'actors'` in the world (the default) or `'widgets'` of the game's UI.
406
+ */
407
+ inspect(options?: {
408
+ mode?: 'actors' | 'widgets';
409
+ }): Promise<void>;
391
410
  console(commandString: string): Promise<void>;
392
411
  /**
393
412
  * Adjusts the global time dilation of the Unreal Engine.
@@ -750,6 +750,46 @@ class SpecterWorld {
750
750
  return new locators_1.SpecterLocator(this.transport, [{ action: 'getUObject', value: className }]);
751
751
  }
752
752
  // --- Global Commands ---
753
+ /**
754
+ * Pauses the test and opens the in-game inspector, the way `page.pause()` opens Playwright's inspector.
755
+ *
756
+ * The game stays exactly as the test left it. Click actors or widgets in the game view to get locators
757
+ * for them, checked against the live game, along with their tags, attributes and components. The test
758
+ * carries on when you close the inspector. Its timeout is switched off while you look around.
759
+ *
760
+ * For writing and debugging tests on your own machine: it does nothing on CI.
761
+ *
762
+ * ```ts
763
+ * const steel = await server.heroes.steel.spawn({ ... });
764
+ * await world.inspect(); // look around, copy a locator, close the inspector to continue
765
+ * ```
766
+ *
767
+ * @param options.mode What to pick first: `'actors'` in the world (the default) or `'widgets'` of the game's UI.
768
+ */
769
+ async inspect(options = {}) {
770
+ if (process.env.CI) {
771
+ return;
772
+ }
773
+ await test_1.default.step(`${this.transport.friendlyPortTag}inspect (waiting for the inspector to be closed)`, async () => {
774
+ // You decide how long this takes, so the test can't time out while it waits
775
+ test_1.default.setTimeout(0);
776
+ let onClosed = () => { };
777
+ const closed = new Promise((resolve) => {
778
+ onClosed = () => resolve();
779
+ });
780
+ this.transport.registerEventListener('GLOBAL_inspector-closed', onClosed);
781
+ try {
782
+ await this.transport.sendCommand({
783
+ command: 'OpenInspector',
784
+ payload: { mode: options.mode ?? 'actors' }
785
+ });
786
+ await closed;
787
+ }
788
+ finally {
789
+ this.transport.removeEventListener('GLOBAL_inspector-closed', onClosed);
790
+ }
791
+ });
792
+ }
753
793
  async console(commandString) {
754
794
  await test_1.default.step(`Specter Console: ${commandString}`, async () => {
755
795
  await this.evaluate('ConsoleCommand', { command: commandString });
@@ -11,8 +11,25 @@ export default class SpecterReporter implements Reporter {
11
11
  private sentImages;
12
12
  /** The step each test failed at (the first failing step outside hooks), so the failure screenshot can sit next to it. */
13
13
  private failedSteps;
14
+ private runStartedAt;
15
+ /** Where tests are staged until the run ends: specter-traces/.run-<stamp> */
16
+ private runStageDir;
17
+ /** Staged tests by name. A retried test replaces its earlier attempt. */
18
+ private runTests;
19
+ private runTestCounter;
20
+ private runHasFailure;
21
+ private runReplay;
22
+ private runReplayWaiters;
23
+ /** Where the engine is writing each test's timeline preview frames (its latest attempt), on the engine's machine */
24
+ private runFrameFolders;
14
25
  constructor();
15
26
  private connect;
27
+ /**
28
+ * The engine broadcasts everything to every client, so most messages here are other clients' command
29
+ * responses. Only the ones about the run's replay and the tests' preview frames matter to the reporter.
30
+ */
31
+ private handleEngineMessage;
32
+ private releaseReplayWaiters;
16
33
  private recordedEvents;
17
34
  private send;
18
35
  onBegin(config: FullConfig, suite: Suite): void;
@@ -40,5 +57,13 @@ export default class SpecterReporter implements Reporter {
40
57
  onStdErr(chunk: string | Buffer, test: void | TestCase, result: void | TestResult): void;
41
58
  onTestEnd(test: TestCase, result: TestResult): void;
42
59
  private saveTraceFile;
43
- onEnd(result: FullResult): void;
60
+ private runTraceMode;
61
+ private stageTestForRunTrace;
62
+ /**
63
+ * Waits for the engine to say the replay is finished, then for the file to stop growing (the engine
64
+ * writes it in the background). Returns the file to pack, or null when there is no replay to include.
65
+ */
66
+ private waitForRunReplay;
67
+ private saveRunTrace;
68
+ onEnd(result: FullResult): Promise<void>;
44
69
  }
@@ -42,6 +42,17 @@ const fs = __importStar(require("fs"));
42
42
  const os = __importStar(require("os"));
43
43
  const path = __importStar(require("path"));
44
44
  const specter_matcher_report_1 = require("./specter-matcher-report");
45
+ const specter_zip_1 = require("./specter-zip");
46
+ function pad(value, length = 2) {
47
+ return String(value).padStart(length, '0');
48
+ }
49
+ /** 20261006-114502, in local time: sorts by name in recording order */
50
+ function fileStamp(date) {
51
+ return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
52
+ }
53
+ function sleep(ms) {
54
+ return new Promise(resolve => setTimeout(resolve, ms));
55
+ }
45
56
  function extractLocatorFromExpectTitle(title) {
46
57
  if (!title.startsWith('expect('))
47
58
  return '';
@@ -104,6 +115,18 @@ class SpecterReporter {
104
115
  sentImages = new Map();
105
116
  /** The step each test failed at (the first failing step outside hooks), so the failure screenshot can sit next to it. */
106
117
  failedSteps = new Map();
118
+ // --- Run trace: one archive holding every test of the run and the run's replay ---
119
+ runStartedAt = new Date();
120
+ /** Where tests are staged until the run ends: specter-traces/.run-<stamp> */
121
+ runStageDir = null;
122
+ /** Staged tests by name. A retried test replaces its earlier attempt. */
123
+ runTests = new Map();
124
+ runTestCounter = 0;
125
+ runHasFailure = false;
126
+ runReplay = null;
127
+ runReplayWaiters = [];
128
+ /** Where the engine is writing each test's timeline preview frames (its latest attempt), on the engine's machine */
129
+ runFrameFolders = new Map();
107
130
  constructor() {
108
131
  this.connect();
109
132
  }
@@ -124,7 +147,66 @@ class SpecterReporter {
124
147
  });
125
148
  socket.on('close', () => {
126
149
  this.isConnected = false;
150
+ // Nothing more will arrive: stop waiting for the replay
151
+ this.releaseReplayWaiters();
127
152
  });
153
+ socket.on('message', (data) => {
154
+ this.handleEngineMessage(data);
155
+ });
156
+ }
157
+ /**
158
+ * The engine broadcasts everything to every client, so most messages here are other clients' command
159
+ * responses. Only the ones about the run's replay and the tests' preview frames matter to the reporter.
160
+ */
161
+ handleEngineMessage(data) {
162
+ try {
163
+ const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.isBuffer(data) ? data : Buffer.from(data);
164
+ if (!buffer.includes('run-replay') && !buffer.includes('test-filmstrip')) {
165
+ return;
166
+ }
167
+ const message = JSON.parse(buffer.toString('utf-8'));
168
+ if (message?.type !== 'event' || !message.data) {
169
+ return;
170
+ }
171
+ if (message.eventName === 'test-filmstrip' && message.data.testName && message.data.folder) {
172
+ // The engine is recording small images of the game view for this test (the timeline's hover preview)
173
+ this.runFrameFolders.set(String(message.data.testName), String(message.data.folder));
174
+ }
175
+ else if (message.eventName === 'run-replay-started' && message.data.replayName) {
176
+ // Recording began. Remember where the file will be in case the engine goes away before the run ends.
177
+ this.runReplay = {
178
+ name: String(message.data.replayName),
179
+ file: String(message.data.replayFile ?? ''),
180
+ tests: new Map(),
181
+ finished: false
182
+ };
183
+ }
184
+ else if (message.eventName === 'run-replay' && message.data.replayName) {
185
+ const tests = new Map();
186
+ for (const entry of Array.isArray(message.data.tests) ? message.data.tests : []) {
187
+ if (entry?.testName) {
188
+ tests.set(String(entry.testName), { start: Number(entry.start ?? -1), end: Number(entry.end ?? -1) });
189
+ }
190
+ }
191
+ this.runReplay = {
192
+ name: String(message.data.replayName),
193
+ file: String(message.data.replayFile ?? this.runReplay?.file ?? ''),
194
+ tests,
195
+ finished: true
196
+ };
197
+ this.releaseReplayWaiters();
198
+ }
199
+ }
200
+ catch {
201
+ // Not ours, or not JSON
202
+ }
203
+ }
204
+ releaseReplayWaiters() {
205
+ const waiters = this.runReplayWaiters;
206
+ this.runReplayWaiters = [];
207
+ for (const resolve of waiters) {
208
+ resolve();
209
+ }
128
210
  }
129
211
  recordedEvents = new Map();
130
212
  send(payload) {
@@ -151,6 +233,7 @@ class SpecterReporter {
151
233
  }
152
234
  }
153
235
  onBegin(config, suite) {
236
+ this.runStartedAt = new Date();
154
237
  this.send({
155
238
  event: 'run_started',
156
239
  payload: {}
@@ -564,6 +647,8 @@ class SpecterReporter {
564
647
  status: result.status
565
648
  }
566
649
  });
650
+ // Every test goes into the run trace, passed or not (before the events are dropped below)
651
+ this.stageTestForRunTrace(uniqueTestKey, test, result);
567
652
  // Determine if portable trace should be saved:
568
653
  // Default: save on failure, on CI, or when SPECTER_TRACE !== 'off'
569
654
  const isFailure = result.status !== 'passed';
@@ -622,13 +707,264 @@ class SpecterReporter {
622
707
  this.recordedEvents.delete(testKey);
623
708
  }
624
709
  }
625
- onEnd(result) {
710
+ // ------------------------------------------------------------------------------------------------
711
+ // Run trace
712
+ //
713
+ // One file for the whole run: specter-traces/run-<stamp>.specter-trace.zip
714
+ //
715
+ // run.json what ran, and where everything is
716
+ // tests/001_<name>/trace.json one test: the same content as a single-test trace
717
+ // tests/001_<name>/screenshots/*.png its images
718
+ // tests/001_<name>/frames/f_*.jpg small frames of the game view, for the timeline's hover preview
719
+ // replay/<name>.replay the engine's replay of the run, when it recorded one
720
+ //
721
+ // Tests are staged on disk as they finish, so a long run doesn't sit in memory, and the archive is
722
+ // written when the run ends. Saved when a test failed, on CI, or with SPECTER_TRACE=on; never with
723
+ // SPECTER_TRACE=off.
724
+ // ------------------------------------------------------------------------------------------------
725
+ runTraceMode() {
726
+ const traceEnv = process.env.SPECTER_TRACE;
727
+ if (traceEnv === 'off')
728
+ return 'off';
729
+ if (traceEnv === 'on' || traceEnv === 'always')
730
+ return 'on';
731
+ return 'auto';
732
+ }
733
+ stageTestForRunTrace(testKey, test, result) {
734
+ if (this.runTraceMode() === 'off') {
735
+ return;
736
+ }
737
+ try {
738
+ if (!this.runStageDir) {
739
+ this.runStageDir = path.resolve(process.cwd(), 'specter-traces', `.run-${fileStamp(this.runStartedAt)}-${process.pid}`);
740
+ fs.rmSync(this.runStageDir, { recursive: true, force: true });
741
+ }
742
+ // A retry replaces the earlier attempt and keeps its place in the run
743
+ const previous = this.runTests.get(testKey);
744
+ const folder = previous?.folder
745
+ ?? `tests/${pad(++this.runTestCounter, 3)}_${testKey.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 60)}`;
746
+ const testDir = path.join(this.runStageDir, folder);
747
+ fs.rmSync(testDir, { recursive: true, force: true });
748
+ fs.mkdirSync(testDir, { recursive: true });
749
+ // Images are copied now: Playwright clears a test's output folder on retry and on the next run.
750
+ // They are listed by the path the events refer to, so two images with the same name stay apart.
751
+ const events = this.recordedEvents.get(testKey) || [];
752
+ const screenshotFiles = {};
753
+ const addImage = (name, sourcePath) => {
754
+ if (!sourcePath || screenshotFiles[sourcePath] || !fs.existsSync(sourcePath)) {
755
+ return;
756
+ }
757
+ const index = Object.keys(screenshotFiles).length + 1;
758
+ const safeName = (name || path.basename(sourcePath)).replace(/\.[a-zA-Z0-9]+$/, '').replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 60);
759
+ const relative = `screenshots/${pad(index)}_${safeName}.png`;
760
+ try {
761
+ fs.mkdirSync(path.join(testDir, 'screenshots'), { recursive: true });
762
+ fs.copyFileSync(sourcePath, path.join(testDir, relative));
763
+ screenshotFiles[sourcePath] = relative;
764
+ }
765
+ catch { }
766
+ };
767
+ for (const recorded of events) {
768
+ if (recorded.event === 'attachment') {
769
+ addImage(recorded.payload?.name, recorded.payload?.path);
770
+ }
771
+ }
772
+ for (const attachment of result.attachments) {
773
+ if (attachment.contentType.startsWith('image/')) {
774
+ addImage(attachment.name, attachment.path);
775
+ }
776
+ }
777
+ const tracePayload = {
778
+ specterTraceVersion: '1.0',
779
+ testName: testKey,
780
+ file: test.location?.file,
781
+ line: test.location?.line,
782
+ status: result.status,
783
+ durationMs: result.duration,
784
+ error: result.error ? this.formatError(result.error, result) : undefined,
785
+ recordedAt: new Date().toISOString(),
786
+ events,
787
+ screenshotFiles
788
+ };
789
+ fs.writeFileSync(path.join(testDir, 'trace.json'), JSON.stringify(tracePayload), 'utf-8');
790
+ this.runTests.set(testKey, {
791
+ testName: testKey,
792
+ folder,
793
+ file: test.location?.file,
794
+ line: test.location?.line,
795
+ status: result.status,
796
+ durationMs: result.duration
797
+ });
798
+ if (result.status !== 'passed' && result.status !== 'skipped') {
799
+ this.runHasFailure = true;
800
+ }
801
+ }
802
+ catch (e) {
803
+ console.error(`[Specter Trace] Failed to stage ${testKey} for the run trace:`, e);
804
+ }
805
+ }
806
+ /**
807
+ * Waits for the engine to say the replay is finished, then for the file to stop growing (the engine
808
+ * writes it in the background). Returns the file to pack, or null when there is no replay to include.
809
+ */
810
+ async waitForRunReplay() {
811
+ // The engine announces a recording when the run starts. No announcement: no replay, and no waiting
812
+ // (beyond a moment for one still on its way after a very short run).
813
+ if (!this.runReplay && this.isConnected) {
814
+ await sleep(300);
815
+ }
816
+ if (!this.runReplay) {
817
+ return null;
818
+ }
819
+ if (!this.runReplay.finished && this.isConnected) {
820
+ await Promise.race([
821
+ new Promise(resolve => this.runReplayWaiters.push(resolve)),
822
+ sleep(5000)
823
+ ]);
824
+ }
825
+ const replayFile = this.runReplay.file;
826
+ if (!replayFile) {
827
+ return null;
828
+ }
829
+ let lastSize = -1;
830
+ for (let attempt = 0; attempt < 20; attempt++) {
831
+ let size = -1;
832
+ try {
833
+ size = fs.statSync(replayFile).size;
834
+ }
835
+ catch { }
836
+ if (size > 0 && size === lastSize) {
837
+ return replayFile;
838
+ }
839
+ lastSize = size;
840
+ await sleep(150);
841
+ }
842
+ // Not on this machine (the game runs elsewhere), or it never settled
843
+ return lastSize > 0 ? replayFile : null;
844
+ }
845
+ async saveRunTrace(result) {
846
+ const stageDir = this.runStageDir;
847
+ if (!stageDir) {
848
+ return;
849
+ }
850
+ const mode = this.runTraceMode();
851
+ const shouldSave = this.runTests.size > 0
852
+ && (mode === 'on' || (mode === 'auto' && (this.runHasFailure || process.env.CI !== undefined)));
853
+ let zip = null;
854
+ let partialPath = '';
855
+ try {
856
+ if (!shouldSave) {
857
+ return;
858
+ }
859
+ const replayFile = await this.waitForRunReplay();
860
+ // The engine writes preview frames in the background: give the last test's final ones a moment to land
861
+ if (this.runFrameFolders.size > 0) {
862
+ await sleep(250);
863
+ }
864
+ const frameFiles = new Map();
865
+ for (const entry of this.runTests.values()) {
866
+ const frameDir = this.runFrameFolders.get(entry.testName) ?? this.runFrameFolders.get(entry.testName.replace(/\\/g, '/'));
867
+ if (!frameDir) {
868
+ continue;
869
+ }
870
+ try {
871
+ // f_0001240.jpg = 1.240 s into the test. Frames still being written have another extension.
872
+ const names = fs.readdirSync(frameDir).filter(name => /^f_\d+\.jpg$/.test(name)).sort();
873
+ if (names.length > 0) {
874
+ frameFiles.set(entry.testName, names.map(name => path.join(frameDir, name)));
875
+ }
876
+ }
877
+ catch {
878
+ // Not on this machine (the game runs elsewhere): the trace goes without preview frames
879
+ }
880
+ }
881
+ // A plain zip holds 65,535 files. A very large run keeps every Nth frame instead of failing.
882
+ const totalFrames = [...frameFiles.values()].reduce((sum, files) => sum + files.length, 0);
883
+ const frameStride = Math.ceil(totalFrames / 50000);
884
+ if (frameStride > 1) {
885
+ for (const [testName, files] of frameFiles) {
886
+ frameFiles.set(testName, files.filter((_, index) => index % frameStride === 0 || index === files.length - 1));
887
+ }
888
+ }
889
+ const replay = this.runReplay;
890
+ const replayEntry = replay && replayFile
891
+ ? `replay/${replay.name.replace(/[^a-zA-Z0-9._-]/g, '_')}.replay`
892
+ : null;
893
+ const tests = [...this.runTests.values()].sort((a, b) => a.folder.localeCompare(b.folder));
894
+ const manifest = {
895
+ specterRunTraceVersion: '1.0',
896
+ recordedAt: this.runStartedAt.toISOString(),
897
+ status: result.status,
898
+ durationMs: Math.round(result.duration),
899
+ tests: tests.map(entry => {
900
+ const span = replayEntry ? replay?.tests.get(entry.testName) ?? replay?.tests.get(entry.testName.replace(/\\/g, '/')) : undefined;
901
+ return {
902
+ testName: entry.testName,
903
+ file: entry.file,
904
+ line: entry.line,
905
+ status: entry.status,
906
+ durationMs: entry.durationMs,
907
+ trace: `${entry.folder}/trace.json`,
908
+ frames: frameFiles.has(entry.testName) ? `${entry.folder}/frames` : undefined,
909
+ replayStart: span?.start,
910
+ replayEnd: span?.end
911
+ };
912
+ }),
913
+ replay: replay && replayEntry ? { name: replay.name, file: replayEntry } : undefined
914
+ };
915
+ const traceDir = path.dirname(stageDir);
916
+ const finalPath = path.join(traceDir, `run-${fileStamp(this.runStartedAt)}.specter-trace.zip`);
917
+ partialPath = `${finalPath}.partial`;
918
+ zip = new specter_zip_1.SpecterZipWriter(partialPath);
919
+ zip.addFile('run.json', Buffer.from(JSON.stringify(manifest, null, 2), 'utf-8'));
920
+ for (const entry of tests) {
921
+ const testDir = path.join(stageDir, entry.folder);
922
+ zip.addFile(`${entry.folder}/trace.json`, fs.readFileSync(path.join(testDir, 'trace.json')));
923
+ const imageDir = path.join(testDir, 'screenshots');
924
+ if (fs.existsSync(imageDir)) {
925
+ for (const image of fs.readdirSync(imageDir).sort()) {
926
+ zip.addFile(`${entry.folder}/screenshots/${image}`, fs.readFileSync(path.join(imageDir, image)), { store: true });
927
+ }
928
+ }
929
+ for (const frame of frameFiles.get(entry.testName) ?? []) {
930
+ try {
931
+ zip.addFile(`${entry.folder}/frames/${path.basename(frame)}`, fs.readFileSync(frame), { store: true });
932
+ }
933
+ catch { }
934
+ }
935
+ }
936
+ if (replayFile && replayEntry) {
937
+ zip.addFile(replayEntry, fs.readFileSync(replayFile));
938
+ }
939
+ zip.close();
940
+ fs.rmSync(finalPath, { force: true });
941
+ fs.renameSync(partialPath, finalPath);
942
+ partialPath = '';
943
+ const failed = tests.filter(entry => entry.status !== 'passed' && entry.status !== 'skipped').length;
944
+ console.log(`[Specter Trace] Saved run trace (${tests.length} test${tests.length === 1 ? '' : 's'}, ${failed} failed, ${replayEntry ? 'with replay' : 'no replay'}) to: ${finalPath}`);
945
+ }
946
+ catch (e) {
947
+ console.error('[Specter Trace] Failed to write the run trace:', e);
948
+ zip?.abort();
949
+ }
950
+ finally {
951
+ if (partialPath) {
952
+ fs.rmSync(partialPath, { force: true });
953
+ }
954
+ fs.rmSync(stageDir, { recursive: true, force: true });
955
+ this.runStageDir = null;
956
+ this.runTests.clear();
957
+ this.runFrameFolders.clear();
958
+ }
959
+ }
960
+ async onEnd(result) {
626
961
  this.send({
627
962
  event: 'run_ended',
628
963
  payload: {
629
964
  status: result.status
630
965
  }
631
966
  });
967
+ await this.saveRunTrace(result);
632
968
  }
633
969
  }
634
970
  exports.default = SpecterReporter;
@@ -0,0 +1,21 @@
1
+ export declare class SpecterZipWriter {
2
+ private readonly filePath;
3
+ private fd;
4
+ private offset;
5
+ private entries;
6
+ private closed;
7
+ constructor(filePath: string);
8
+ /**
9
+ * Adds a file. `name` is its path inside the archive, with forward slashes.
10
+ * Pass `store: true` for data that is already compressed (PNG images).
11
+ */
12
+ addFile(name: string, data: Buffer, options?: {
13
+ store?: boolean;
14
+ date?: Date;
15
+ }): void;
16
+ /** Writes the directory and closes the file. The archive isn't readable until this has run. */
17
+ close(): void;
18
+ /** Closes the file without finishing the archive (after an error). */
19
+ abort(): void;
20
+ private write;
21
+ }
@@ -0,0 +1,195 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.SpecterZipWriter = void 0;
37
+ const fs = __importStar(require("fs"));
38
+ const zlib = __importStar(require("zlib"));
39
+ /**
40
+ * A minimal .zip writer for run traces, so the package needs no archive dependency.
41
+ * Entries are written one at a time straight to disk (nothing but the entry in hand is held in memory).
42
+ * Plain zip only: no zip64, so the archive and each entry must stay under 4 GB and 65,535 entries.
43
+ */
44
+ const CRC_TABLE = (() => {
45
+ const table = new Uint32Array(256);
46
+ for (let n = 0; n < 256; n++) {
47
+ let c = n;
48
+ for (let k = 0; k < 8; k++) {
49
+ c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
50
+ }
51
+ table[n] = c >>> 0;
52
+ }
53
+ return table;
54
+ })();
55
+ function crc32(data) {
56
+ // Node 20.15+/22.2+ has a native one
57
+ const native = zlib.crc32;
58
+ if (typeof native === 'function') {
59
+ return native(data) >>> 0;
60
+ }
61
+ let crc = 0xffffffff;
62
+ for (let i = 0; i < data.length; i++) {
63
+ crc = CRC_TABLE[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
64
+ }
65
+ return (crc ^ 0xffffffff) >>> 0;
66
+ }
67
+ const MAX_UINT32 = 0xffffffff;
68
+ const MAX_ENTRIES = 0xffff;
69
+ /** Bit 11: entry names are UTF-8 */
70
+ const FLAG_UTF8 = 0x0800;
71
+ class SpecterZipWriter {
72
+ filePath;
73
+ fd;
74
+ offset = 0;
75
+ entries = [];
76
+ closed = false;
77
+ constructor(filePath) {
78
+ this.filePath = filePath;
79
+ this.fd = fs.openSync(filePath, 'w');
80
+ }
81
+ /**
82
+ * Adds a file. `name` is its path inside the archive, with forward slashes.
83
+ * Pass `store: true` for data that is already compressed (PNG images).
84
+ */
85
+ addFile(name, data, options = {}) {
86
+ if (this.closed) {
87
+ throw new Error('The archive is already closed');
88
+ }
89
+ const entryName = name.replace(/\\/g, '/').replace(/^\/+/, '');
90
+ if (!entryName || entryName.split('/').includes('..')) {
91
+ throw new Error(`Invalid archive entry name: ${name}`);
92
+ }
93
+ if (this.entries.length >= MAX_ENTRIES) {
94
+ throw new Error('Too many files for a zip archive (65,535 at most)');
95
+ }
96
+ let method = 0;
97
+ let body = data;
98
+ if (!options.store && data.length > 0) {
99
+ const deflated = zlib.deflateRawSync(data, { level: 6 });
100
+ if (deflated.length < data.length) {
101
+ method = 8;
102
+ body = deflated;
103
+ }
104
+ }
105
+ if (data.length > MAX_UINT32 || this.offset + body.length > MAX_UINT32) {
106
+ throw new Error('The archive would be larger than 4 GB');
107
+ }
108
+ const date = options.date ?? new Date();
109
+ const dosTime = (date.getHours() << 11) | (date.getMinutes() << 5) | (date.getSeconds() >> 1);
110
+ const dosDate = (Math.max(0, date.getFullYear() - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate();
111
+ const entry = {
112
+ name: Buffer.from(entryName, 'utf-8'),
113
+ method,
114
+ crc: crc32(data),
115
+ compressedSize: body.length,
116
+ size: data.length,
117
+ offset: this.offset,
118
+ dosTime,
119
+ dosDate
120
+ };
121
+ const header = Buffer.alloc(30);
122
+ header.writeUInt32LE(0x04034b50, 0);
123
+ header.writeUInt16LE(20, 4); // version needed
124
+ header.writeUInt16LE(FLAG_UTF8, 6);
125
+ header.writeUInt16LE(entry.method, 8);
126
+ header.writeUInt16LE(entry.dosTime, 10);
127
+ header.writeUInt16LE(entry.dosDate, 12);
128
+ header.writeUInt32LE(entry.crc, 14);
129
+ header.writeUInt32LE(entry.compressedSize, 18);
130
+ header.writeUInt32LE(entry.size, 22);
131
+ header.writeUInt16LE(entry.name.length, 26);
132
+ header.writeUInt16LE(0, 28); // extra field length
133
+ this.write(header);
134
+ this.write(entry.name);
135
+ this.write(body);
136
+ this.entries.push(entry);
137
+ }
138
+ /** Writes the directory and closes the file. The archive isn't readable until this has run. */
139
+ close() {
140
+ if (this.closed) {
141
+ return;
142
+ }
143
+ this.closed = true;
144
+ const directoryOffset = this.offset;
145
+ for (const entry of this.entries) {
146
+ const record = Buffer.alloc(46);
147
+ record.writeUInt32LE(0x02014b50, 0);
148
+ record.writeUInt16LE(20, 4); // version made by
149
+ record.writeUInt16LE(20, 6); // version needed
150
+ record.writeUInt16LE(FLAG_UTF8, 8);
151
+ record.writeUInt16LE(entry.method, 10);
152
+ record.writeUInt16LE(entry.dosTime, 12);
153
+ record.writeUInt16LE(entry.dosDate, 14);
154
+ record.writeUInt32LE(entry.crc, 16);
155
+ record.writeUInt32LE(entry.compressedSize, 20);
156
+ record.writeUInt32LE(entry.size, 24);
157
+ record.writeUInt16LE(entry.name.length, 28);
158
+ // extra length, comment length, disk number, internal attributes (2 bytes each), external attributes (4)
159
+ record.writeUInt32LE(entry.offset, 42);
160
+ this.write(record);
161
+ this.write(entry.name);
162
+ }
163
+ const directorySize = this.offset - directoryOffset;
164
+ if (this.offset > MAX_UINT32) {
165
+ fs.closeSync(this.fd);
166
+ throw new Error('The archive would be larger than 4 GB');
167
+ }
168
+ const end = Buffer.alloc(22);
169
+ end.writeUInt32LE(0x06054b50, 0);
170
+ end.writeUInt16LE(this.entries.length, 8);
171
+ end.writeUInt16LE(this.entries.length, 10);
172
+ end.writeUInt32LE(directorySize, 12);
173
+ end.writeUInt32LE(directoryOffset, 16);
174
+ this.write(end);
175
+ fs.closeSync(this.fd);
176
+ }
177
+ /** Closes the file without finishing the archive (after an error). */
178
+ abort() {
179
+ if (!this.closed) {
180
+ this.closed = true;
181
+ try {
182
+ fs.closeSync(this.fd);
183
+ }
184
+ catch { }
185
+ }
186
+ }
187
+ write(data) {
188
+ let written = 0;
189
+ while (written < data.length) {
190
+ written += fs.writeSync(this.fd, data, written, data.length - written);
191
+ }
192
+ this.offset += data.length;
193
+ }
194
+ }
195
+ exports.SpecterZipWriter = SpecterZipWriter;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.128",
3
+ "version": "1.0.130",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",