unittas 0.1.0.dev19__py3-none-any.whl

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.
Files changed (65) hide show
  1. unittas/__init__.py +30 -0
  2. unittas/__main__.py +11 -0
  3. unittas/_test_world.py +410 -0
  4. unittas/agent.py +1385 -0
  5. unittas/api.py +569 -0
  6. unittas/blockview.py +365 -0
  7. unittas/box.py +20 -0
  8. unittas/cache.py +139 -0
  9. unittas/classheaders.py +68 -0
  10. unittas/cli.py +146 -0
  11. unittas/codec.py +478 -0
  12. unittas/compare.py +138 -0
  13. unittas/container.py +43 -0
  14. unittas/dev.py +40 -0
  15. unittas/display.py +67 -0
  16. unittas/errors.py +313 -0
  17. unittas/game.py +275 -0
  18. unittas/gamefiles.py +162 -0
  19. unittas/gamemode.py +17 -0
  20. unittas/gameoutput.py +50 -0
  21. unittas/intermediary.py +69 -0
  22. unittas/launcher.py +968 -0
  23. unittas/levels.py +99 -0
  24. unittas/likeness.py +141 -0
  25. unittas/link.py +520 -0
  26. unittas/mappings.py +130 -0
  27. unittas/mojangnames.py +251 -0
  28. unittas/multiplayer.py +253 -0
  29. unittas/nearblock.py +48 -0
  30. unittas/perception.py +47 -0
  31. unittas/png.py +125 -0
  32. unittas/probes/unittas-0.1.0-dev19.jar +0 -0
  33. unittas/probes/unittas-probe-1.20.1-0.1.0-dev19.jar +0 -0
  34. unittas/probes/unittas-probe-1.21.1-0.1.0-dev19.jar +0 -0
  35. unittas/probes/unittas-probe-26.3-0.1.0-dev19.jar +0 -0
  36. unittas/release.py +165 -0
  37. unittas/reset.py +100 -0
  38. unittas/run.py +1077 -0
  39. unittas/scenario.py +74 -0
  40. unittas/scene.py +148 -0
  41. unittas/selftest.py +132 -0
  42. unittas/servergame.py +207 -0
  43. unittas/session.py +660 -0
  44. unittas/snbt.py +268 -0
  45. unittas/spec.py +375 -0
  46. unittas/specgame.py +321 -0
  47. unittas/srgnames.py +75 -0
  48. unittas/target.py +49 -0
  49. unittas/terrain.py +402 -0
  50. unittas/testcase.py +403 -0
  51. unittas/thing.py +238 -0
  52. unittas/things.py +415 -0
  53. unittas/values.py +275 -0
  54. unittas/versions.py +251 -0
  55. unittas/watch.py +574 -0
  56. unittas/watcher.py +178 -0
  57. unittas/wire.py +217 -0
  58. unittas/worldkind.py +19 -0
  59. unittas/worldrun.py +119 -0
  60. unittas-0.1.0.dev19.dist-info/METADATA +71 -0
  61. unittas-0.1.0.dev19.dist-info/RECORD +65 -0
  62. unittas-0.1.0.dev19.dist-info/WHEEL +5 -0
  63. unittas-0.1.0.dev19.dist-info/entry_points.txt +2 -0
  64. unittas-0.1.0.dev19.dist-info/licenses/LICENSE +201 -0
  65. unittas-0.1.0.dev19.dist-info/top_level.txt +1 -0
unittas/__init__.py ADDED
@@ -0,0 +1,30 @@
1
+ """
2
+ The 'unittas' package is the Python side of unitTAS: the orchestrator that
3
+ starts Minecraft, and the protocol it speaks with the probe inside the game
4
+ (PROTOCOL.md). Being built, phase 3 of the pivot (SPEC.md section 9).
5
+
6
+ - wire: the protocol's closed sets and its messages, as lines of JSON.
7
+ - errors: one exception for each error type an answer can carry.
8
+ - link: the listener, the start file, and a connection to one game.
9
+ - values, codec: the protocol's values, and their JSON edge.
10
+ - snbt: NBT as SNBT text, read into a typed tree and written back.
11
+ - spec: the instance spec, a TOML file saying which game a run needs.
12
+ - cache, launcher: the download cache, and the real client's launch.
13
+ - mappings: readable (MCP) names to the game's, for reflection.
14
+ - api: Game, the face of a game a test speaks to.
15
+ - game, dev, release: the games the probe's own tests start; gamefiles,
16
+ the game folder's own files kept aside and put back.
17
+ - display: the test display (gamescope) in front of a game.
18
+ - specgame: the game an instance spec names, real or the mod's Gradle run.
19
+ - reset: the reset, in PROTOCOL.md 9.5's order.
20
+ - run, testcase: a run's lifecycle and report, and GameTestCase.
21
+ - session, cli: the 'unittas' command (run, launch, compare), and the run
22
+ plain unittest starts from the spec.
23
+ - compare: two reports compared test by test.
24
+ - selftest: the probe's own tests, in one game.
25
+ """
26
+ # Apache-2.0 license
27
+ # Copyright (c) 2026 Asger Jon Vistisen
28
+ from __future__ import annotations
29
+
30
+ __version__ = '0.1.0-dev19'
unittas/__main__.py ADDED
@@ -0,0 +1,11 @@
1
+ """'python -m unittas ...' is the 'unittas' command (unittas.cli)."""
2
+ # Apache-2.0 license
3
+ # Copyright (c) 2026 Asger Jon Vistisen
4
+ from __future__ import annotations
5
+
6
+ import sys
7
+
8
+ from .cli import main
9
+
10
+ if __name__ == '__main__':
11
+ sys.exit(main())
unittas/_test_world.py ADDED
@@ -0,0 +1,410 @@
1
+ """
2
+ World encapsulates a minecraft world used for testing.
3
+ """
4
+ # Apache-2.0 license
5
+ # Copyright (c) 2026 Asger Jon Vistisen
6
+ from __future__ import annotations
7
+
8
+ from types import FunctionType
9
+ from typing import TYPE_CHECKING
10
+
11
+ from mcdex import MCBiomes
12
+ from worktoy.desc import Field, FixBox
13
+ from worktoy.dispatch import overload
14
+ from worktoy.mcls import BaseObject
15
+
16
+ from .gamemode import GameMode
17
+ from .values import BlockPos
18
+ from .worldkind import WorldKind
19
+
20
+ if TYPE_CHECKING: # pragma: no cover
21
+ from typing import Any, Callable, Optional
22
+
23
+ from mcdex import MCBlocks, MCStructures, Version
24
+
25
+ from .api import Game
26
+ from .values import Vec3
27
+
28
+
29
+ class World(BaseObject):
30
+ """
31
+ A Minecraft world for tests (SPEC.md 17). Each world is a subclass, its
32
+ options 'FixBox' fields redeclared in its body and its setup its own
33
+ 'setUp'. An instance placed in a test class's body is the world that
34
+ class's tests run in, and it decorates them:
35
+
36
+ class VillagePlains(World):
37
+ seed = FixBox[int](8675309)
38
+
39
+ class VillageTests(UnitTAS):
40
+ plains = VillagePlains()
41
+
42
+ @plains
43
+ def test_a_village_near_spawn(self) -> None:
44
+ ...
45
+
46
+ Decorating records the method's name and returns the method as
47
+ received, before the class exists; placing the instance then runs
48
+ 'Object.__set_name__' exactly once, and 'hookSetName' checks what was
49
+ decorated against the owner. Which world a test of a subclass runs in
50
+ is the run's to find, along the class's MRO (SPEC.md 17.8).
51
+ """
52
+
53
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
54
+ # NAMESPACE # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
55
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
56
+
57
+ # Class Variables
58
+
59
+ # Fallback Variables
60
+
61
+ # Private Variables
62
+ # The test methods this world decorated, by name, as decorated
63
+ __decorated__: dict = None
64
+ # The owner and name of its one placement, once placed
65
+ __placement__: tuple = None
66
+ # What the run handed over on entering (the game, start, spawn), else
67
+ # None while the world isn't entered
68
+ __entered__: dict = None
69
+
70
+ # Public Variables
71
+ # The world's options, in mcdex's terms and unitTAS's own (SPEC.md
72
+ # 17.4): each version makes it as its own. 'layers' are a flat world's,
73
+ # bottom up, (MCBlocks member, thickness); 'flatBiome' is a flat
74
+ # world's too ('biome' is the read, 17.5); 'rules' maps MCGameRules
75
+ # members to their values.
76
+ seed = FixBox[int](0)
77
+ kind = FixBox[WorldKind](WorldKind.Default)
78
+ layers = FixBox[tuple](())
79
+ flatBiome = FixBox[MCBiomes](MCBiomes.Plains)
80
+ rules = FixBox[dict]({})
81
+ gameMode = FixBox[GameMode](GameMode.Creative)
82
+ structures = FixBox[bool](True)
83
+ save = FixBox[str]('')
84
+ fresh = FixBox[bool](False)
85
+
86
+ # Virtual Variables
87
+ start = Field()
88
+ spawn = Field()
89
+ game = Field()
90
+
91
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
92
+ # GETTERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
93
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
94
+
95
+ @start.GET
96
+ def _getStart(self) -> Vec3:
97
+ """Where the game put the player on entering; raises if not entered."""
98
+ return self._getEntered()['start']
99
+
100
+ @spawn.GET
101
+ def _getSpawn(self) -> BlockPos:
102
+ """The world's spawn point, from the game; raises if not entered."""
103
+ return self._getEntered()['spawn']
104
+
105
+ @game.GET
106
+ def _getGame(self) -> Game:
107
+ """The game it's entered in, for its setUp; raises if not entered."""
108
+ return self._getEntered()['game']
109
+
110
+ def _getEntered(self) -> dict:
111
+ """
112
+ What the run handed over on entering.
113
+
114
+ Raises
115
+ ------
116
+ RuntimeError
117
+ The world isn't entered: it answers only in its own tests.
118
+ """
119
+ if self.__entered__ is None:
120
+ infoSpec = """The world '%s' isn't entered: it answers only in the
121
+ tests it decorates, while they run."""
122
+ raise RuntimeError(' '.join((infoSpec % self.label()).split()))
123
+ return self.__entered__
124
+
125
+ def isEntered(self) -> bool:
126
+ """Whether the run has entered this world and not left it."""
127
+ return self.__entered__ is not None
128
+
129
+ def label(self) -> str:
130
+ """'Owner.name' where it's placed, else its class's name."""
131
+ if self.__placement__ is None:
132
+ return type(self).__name__
133
+ owner, name = self.__placement__
134
+ return '%s.%s' % (owner.__name__, name)
135
+
136
+ def createArgs(self, version: Version,
137
+ declared: Optional[dict] = None) -> dict:
138
+ """
139
+ world.create's arguments for this world in the version (PROTOCOL.md):
140
+ its kind, seed, game mode and structures; a flat world's layers as
141
+ that version's blocks, bottom up, and its biome as that version's
142
+ id, from which each probe writes its own generator text. 'declared'
143
+ is the game's mods' declarations (Game.declared).
144
+
145
+ Raises
146
+ ------
147
+ Missing
148
+ A layer's block or the flat biome is one vanilla lacks there and no mod
149
+ declares: the world's sanity check fails (SPEC.md 17.4).
150
+ TypeError
151
+ Layers on a world that isn't flat; a layer that isn't an MCBlocks
152
+ member with a thickness, or one told apart by block entity data.
153
+ TypeError
154
+ A saved map ('save'), which is opened, not made.
155
+ """
156
+ from .things import blockOf, resolve
157
+ if self.save:
158
+ infoSpec = """The world '%s' is the saved map '%s': it's opened from
159
+ a fresh copy (savedFolder), not made."""
160
+ info = infoSpec % (self.label(), self.save)
161
+ raise TypeError(' '.join(info.split()))
162
+ args = {'type': self.kind.value, 'seed': self.seed,
163
+ 'game_mode': self.gameMode.value, 'structures': self.structures}
164
+ if not self.layers:
165
+ return args
166
+ if self.kind is not WorldKind.Flat:
167
+ raise TypeError("%s has layers, which are a flat world's, but its "
168
+ "kind is %s" % (self.label(), self.kind))
169
+ layers = []
170
+ for layer in self.layers:
171
+ if not isinstance(layer, tuple) or len(layer) != 2:
172
+ raise TypeError('%s: a layer is (MCBlocks member, thickness), not %r'
173
+ % (self.label(), layer))
174
+ member, count = layer
175
+ block, tile = blockOf(member, version, declared)
176
+ if tile:
177
+ raise TypeError('%s: %s.%s is told apart by its block entity data '
178
+ 'there, which a layer has none of'
179
+ % (self.label(), type(member).__name__, member.name))
180
+ layer = {'id': block.id}
181
+ # none from 1.13 on (D4)
182
+ if block.meta >= 0:
183
+ layer['meta'] = block.meta
184
+ layer['count'] = count
185
+ layers.append(layer)
186
+ args['layers'] = layers
187
+ args['biome'] = resolve(self.flatBiome, version, declared).text()
188
+ return args
189
+
190
+ def savedFolder(self) -> str:
191
+ """
192
+ A saved map's folder (SPEC.md 17.4): 'save' beside the module that
193
+ declares this World's class, or as given when absolute. The run
194
+ copies it fresh for each use and opens the copy, never the map.
195
+
196
+ Raises
197
+ ------
198
+ TypeError
199
+ This World is no saved map, or it sets options that are the map's
200
+ own (kind, seed, layers, flatBiome, gameMode, structures).
201
+ FileNotFoundError
202
+ No save is there (no level.dat).
203
+ """
204
+ import os
205
+ import sys
206
+ if not self.save:
207
+ raise TypeError('%s is no saved map' % self.label())
208
+ defaults = (('kind', WorldKind.Default), ('seed', 0), ('layers', ()),
209
+ ('flatBiome', MCBiomes.Plains),
210
+ ('gameMode', GameMode.Creative), ('structures', True))
211
+ own = [name for name, value in defaults if getattr(self, name) != value]
212
+ if own:
213
+ raise TypeError("%s is the saved map %s, whose %s are the map's own, "
214
+ "not the World's to set"
215
+ % (self.label(), self.save, ', '.join(own)))
216
+ module = sys.modules.get(type(self).__module__)
217
+ path = getattr(module, '__file__', None)
218
+ if path is None:
219
+ raise TypeError('%s is declared in %s, which has no file to find '
220
+ 'its map beside'
221
+ % (self.label(), type(self).__module__))
222
+ folder = os.path.normpath(os.path.join(
223
+ os.path.dirname(os.path.abspath(path)), self.save))
224
+ if not os.path.isfile(os.path.join(folder, 'level.dat')):
225
+ raise FileNotFoundError('%s: no saved map at %s (no level.dat there)'
226
+ % (self.label(), folder))
227
+ return folder
228
+
229
+ def ruleArgs(self, version: Version,
230
+ declared: Optional[dict] = None) -> dict:
231
+ """
232
+ world.rules.set's rules for this world in the version: each
233
+ MCGameRules member's name there, to its value.
234
+
235
+ Raises
236
+ ------
237
+ Missing
238
+ A rule vanilla lacks there: the world's sanity check fails.
239
+ """
240
+ from .things import resolve
241
+ return {resolve(member, version, declared).text(): value
242
+ for member, value in self.rules.items()}
243
+
244
+ def getDecorated(self) -> tuple[str, ...]:
245
+ """The names of the test methods this world decorated, in order."""
246
+ if self.__decorated__ is None:
247
+ return ()
248
+ return tuple(self.__decorated__)
249
+
250
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
251
+ # SETTERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
252
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
253
+
254
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
255
+ # CONSTRUCTORS # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
256
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
257
+
258
+ def __init__(self) -> None:
259
+ """
260
+ A world with nothing decorated yet and not entered. It takes no
261
+ arguments: its options belong to its class.
262
+ """
263
+ BaseObject.__init__(self)
264
+ self.__decorated__ = {}
265
+
266
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
267
+ # PARENT METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
268
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
269
+
270
+ def hookSetName(self, owner: type, name: str, **kwargs: Any) -> None:
271
+ """
272
+ The placement in a test class's body, exactly once, after every
273
+ decoration in that body.
274
+
275
+ Raises
276
+ ------
277
+ TypeError
278
+ A method this world decorated isn't in the owner's body as it was
279
+ decorated (redefined after its decoration); a method is decorated
280
+ by two worlds; this world is placed a second time; or the owner is
281
+ a MultiplayerTestCase, whose worlds come later (SPEC.md 17.8).
282
+ """
283
+ if self.__placement__ is not None:
284
+ # 'Object.__set_name__' recorded this placement before the hook:
285
+ # the first one is put back, so the refusal changes nothing
286
+ firstOwner, firstName = self.__placement__
287
+ object.__setattr__(self, '__field_owner__', firstOwner)
288
+ object.__setattr__(self, '__field_name__', firstName)
289
+ infoSpec = """The world '%s.%s' is placed again, as '%s.%s'. A world
290
+ is placed once, in the class body that made it; another class
291
+ places a world of its own."""
292
+ info = infoSpec % (firstOwner.__name__, firstName, owner.__name__,
293
+ name)
294
+ raise TypeError(' '.join(info.split()))
295
+ self.__placement__ = (owner, name)
296
+ # here, not at the top: unittas.testcase is the run's, and it uses
297
+ # worlds
298
+ from .testcase import MultiplayerTestCase
299
+ if issubclass(owner, MultiplayerTestCase):
300
+ infoSpec = """The world '%s.%s' is placed in a MultiplayerTestCase:
301
+ worlds on a server aren't there yet (SPEC.md 17.8)."""
302
+ raise TypeError(' '.join((infoSpec % (owner.__name__, name)).split()))
303
+ body = vars(owner)
304
+ for key, method in self.__decorated__.items():
305
+ if body.get(key) is not method:
306
+ infoSpec = """'%s.%s' was decorated by the world '%s', then
307
+ defined again in the class body, which left it without its
308
+ world."""
309
+ info = infoSpec % (owner.__name__, key, name)
310
+ raise TypeError(' '.join(info.split()))
311
+ for otherName, other in body.items():
312
+ if other is self or not isinstance(other, World):
313
+ continue
314
+ for key in self.getDecorated():
315
+ if key in other.getDecorated():
316
+ infoSpec = """'%s.%s' is decorated by two worlds, '%s' and
317
+ '%s'. A test runs in one world."""
318
+ info = infoSpec % (owner.__name__, key, name, otherName)
319
+ raise TypeError(' '.join(info.split()))
320
+
321
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
322
+ # DOMAIN SPECIFIC # # # # # # # # # # # # # # # # # # # # # # # # # # # #
323
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
324
+
325
+ def __call__(self, method: Callable) -> Callable:
326
+ """
327
+ Decorates a test method: records its name, returns it as received.
328
+
329
+ Raises
330
+ ------
331
+ TypeError
332
+ The world is placed already, so nothing would check the decoration
333
+ (a subclass places a world of its own); or 'method' is no plain
334
+ function.
335
+ """
336
+ if not isinstance(method, FunctionType):
337
+ infoSpec = """A world decorates test methods, plain functions in a
338
+ class body, not %r."""
339
+ raise TypeError(' '.join((infoSpec % (method,)).split()))
340
+ if self.__placement__ is not None:
341
+ owner, name = self.__placement__
342
+ infoSpec = """'%s' is decorated by the world '%s.%s', which is
343
+ placed already, so nothing would check the decoration. A class
344
+ places a world of its own for its tests."""
345
+ info = infoSpec % (method.__name__, owner.__name__, name)
346
+ raise TypeError(' '.join(info.split()))
347
+ self.__decorated__[method.__name__] = method
348
+ return method
349
+
350
+ def setUp(self) -> None:
351
+ """A world's own setup: run once when it's made and entered."""
352
+
353
+ def enter(self, game: Game, start: Vec3, spawn: BlockPos) -> None:
354
+ """
355
+ The run hands over the entered world (SPEC.md 17.8).
356
+
357
+ Raises
358
+ ------
359
+ RuntimeError
360
+ It's entered already: the run leaves a world before entering it.
361
+ """
362
+ if self.__entered__ is not None:
363
+ infoSpec = """The world '%s' is entered already: the run leaves it
364
+ first."""
365
+ raise RuntimeError(' '.join((infoSpec % self.label()).split()))
366
+ self.__entered__ = {'game': game, 'start': start, 'spawn': spawn}
367
+
368
+ def leave(self) -> None:
369
+ """
370
+ The run takes the entered world back; reads raise after this.
371
+
372
+ Raises
373
+ ------
374
+ RuntimeError
375
+ It isn't entered.
376
+ """
377
+ self._getEntered()
378
+ self.__entered__ = None
379
+
380
+ @overload(BlockPos)
381
+ def block(self, pos: BlockPos) -> frozenset:
382
+ """The mcdex blocks the block at 'pos' is (SPEC.md 14.3)."""
383
+ raise NotImplementedError
384
+
385
+ @overload(int, int, int)
386
+ def block(self, x: int, y: int, z: int) -> frozenset:
387
+ """The mcdex blocks the block at x, y, z is."""
388
+ return self.block(BlockPos(x, y, z))
389
+
390
+ def fill(self, a: BlockPos, b: BlockPos, block: MCBlocks) -> None:
391
+ """The box from 'a' to 'b' filled with 'block'."""
392
+ raise NotImplementedError
393
+
394
+ @overload(BlockPos)
395
+ def biome(self, pos: BlockPos) -> MCBiomes:
396
+ """The biome at 'pos', as the game holds it."""
397
+ raise NotImplementedError
398
+
399
+ @overload(int, int)
400
+ def ground(self, x: int, z: int) -> BlockPos:
401
+ """The top solid block at x, z, so no test names a height."""
402
+ raise NotImplementedError
403
+
404
+ def nearest(self, structure: MCStructures, pos: BlockPos) -> BlockPos:
405
+ """The nearest structure of that kind, by the game's own search."""
406
+ raise NotImplementedError
407
+
408
+ def generate(self, a: BlockPos, b: BlockPos) -> None:
409
+ """The chunks from 'a' to 'b' generated by the game's generator."""
410
+ raise NotImplementedError