pyathy 0.1.22__tar.gz

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.
@@ -0,0 +1,4 @@
1
+ .venv/
2
+ __pycache__/
3
+ dist/
4
+ .pyathy/
pyathy-0.1.22/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mihai Banulescu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
pyathy-0.1.22/PKG-INFO ADDED
@@ -0,0 +1,318 @@
1
+ Metadata-Version: 2.5
2
+ Name: pyathy
3
+ Version: 0.1.22
4
+ Summary: Python acceptance testing harness (for) you: Gherkin for command-line programs
5
+ Project-URL: Homepage, https://github.com/bluemihai/pyathy
6
+ Project-URL: Documentation, https://github.com/bluemihai/pyathy/tree/main/docs
7
+ Project-URL: Source, https://github.com/bluemihai/pyathy
8
+ Project-URL: Issues, https://github.com/bluemihai/pyathy/issues
9
+ Author: Mihai Banulescu
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: acceptance-testing,bdd,cli,gherkin,pytest-bdd,testing
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Framework :: Pytest
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: Education
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: Python :: 3.14
25
+ Classifier: Topic :: Software Development :: Testing
26
+ Classifier: Topic :: Software Development :: Testing :: Acceptance
27
+ Classifier: Topic :: Software Development :: Testing :: BDD
28
+ Requires-Python: >=3.11
29
+ Requires-Dist: pytest-bdd>=9
30
+ Description-Content-Type: text/markdown
31
+
32
+ # pyathy
33
+
34
+ Test a Python command-line program with scenarios written in plain English.
35
+
36
+ You write `.feature` files (Gherkin: `Scenario`, `When`, `Then`) that type answers into
37
+ the program, fix its dice rolls, and check what it prints. pyathy runs each scenario against
38
+ a fresh start of `main.py` and shows each run, then one `✔`/`✘` line per scenario plus a total.
39
+ It is built on [pytest-bdd](https://github.com/pytest-dev/pytest-bdd) and needs Python 3.11+.
40
+
41
+ It was built for the Saxion ADSD python course, so that the acceptance tests of an assignment
42
+ can be read, and written, by people new to programming: the steps are the words a person
43
+ would use at the keyboard, and no code is needed. It tests any Python command-line program,
44
+ anywhere, the same way.
45
+
46
+ Ruby has this layer already: [Aruba](https://github.com/cucumber/aruba) gives Cucumber
47
+ ready-made steps for command-line programs (run it, type this, expect that output). Python's
48
+ pytest-bdd has no such layer; pyathy is that layer for Python.
49
+
50
+ ## Install and use
51
+
52
+ Four ways to get the command. They run the same features the same way.
53
+
54
+ **From PyPI**, as a command on your PATH:
55
+
56
+ ```
57
+ pipx install pyathy # or: uv tool install pyathy
58
+ ```
59
+
60
+ or inside a project's venv: `pip install pyathy`. For VS Code there is the pyathy extension,
61
+ `MB42.pyathy` in the Marketplace.
62
+
63
+ **No install: the `pyathy/` folder next to `main.py`.** The folder is built from this repo by
64
+ `scripts/build-folder.sh` into `dist/pyathy/`, with pytest-bdd inside, so nothing needs installing:
65
+
66
+ ```
67
+ my-game/
68
+ main.py
69
+ features/
70
+ game.feature
71
+ pyathy/
72
+ ```
73
+
74
+ ```
75
+ python pyathy
76
+ ```
77
+
78
+ In a course, an assignment's package is this folder plus its `features/`, zipped.
79
+
80
+ **Poetry**, with that same `pyathy/` folder in the project:
81
+
82
+ ```
83
+ poetry add ./pyathy
84
+ poetry run pyathy
85
+ ```
86
+
87
+ **pip**, in a venv: `pip install ./pyathy` for the folder, or from a clone of this repo:
88
+
89
+ ```
90
+ python -m venv .venv
91
+ .venv/bin/pip install . # Windows: .venv\Scripts\pip install .
92
+ cd examples/tictactoe
93
+ ../../.venv/bin/pyathy # Windows: ..\..\.venv\Scripts\pyathy
94
+ ```
95
+
96
+ That runs the tic-tac-toe example's features against its `main.py`.
97
+
98
+ From the folder that holds `main.py` and `features/` (write `python pyathy …` for the folder,
99
+ `poetry run pyathy …` under Poetry):
100
+
101
+ ```
102
+ pyathy run every features/*.feature against main.py
103
+ pyathy features/x.feature run only that file (or folder)
104
+ pyathy check find mistakes in the feature files, without running main.py
105
+ pyathy init create features/hello.feature (and a main.py) to start from
106
+ pyathy steps every step you can use (plus your own, from features/*_steps.py)
107
+ pyathy -h usage and an example feature
108
+ ```
109
+
110
+ Options, each with a short and a long form:
111
+
112
+ ```
113
+ -q, --quiet only one line per scenario (a ✘ gets one reason line) and the total
114
+ -ff, --fail-fast stop at the first scenario that fails
115
+ -nf, --next-failure run the scenarios that failed last time, in order, stopping at the first that still fails
116
+ -s, --solution [FOLDER] run the features here against ./_solution/main.py, or ./FOLDER/main.py (-s obj2 means _solution-obj2)
117
+ -o, --output show|hide|slow the program's output in the report: show it (the default), hide it, or slow: a line at a time, to read along (on a terminal only)
118
+ --delay SECONDS the pause after each line under -o slow (default 0.1: a 100-line run takes 10 seconds; --delay alone means -o slow)
119
+ -h, --help this help
120
+ -v, --version pyathy's version and where it runs from
121
+ ```
122
+
123
+ The report shows each scenario's run as a terminal would have (what was printed, what was
124
+ typed), then its `✔`/`✘` line with the reason under a `✘`, a summary per feature, and the last
125
+ line `TOTAL n of m`; `-q` keeps only the `✔`/`✘` lines and the total. Every report ends with
126
+ `pyathy <version> · <where it runs from>`, the same as `-v`, so two copies on one machine are
127
+ never confused. `-nf` reads the failures remembered in `.pyathy/last-run.json`; `-s` is for
128
+ the teacher's folder, where the reference program sits in `_solution/`. The report's colours,
129
+ the long-run cut and the details of `-nf` and `-s`: [docs/running.md](https://github.com/bluemihai/pyathy/blob/main/docs/running.md).
130
+
131
+ `pyathy check` reads the feature files without running the program and lists, per file,
132
+ what would stop a scenario before it starts: a line no step matches (with the closest step,
133
+ `did you mean: I input Ada`), a file that is not valid Gherkin, a scenario or step indented
134
+ differently from the others, and a file step pyathy cannot find in the program. It exits with
135
+ 1 when it found something; `--json` prints the same for an editor (the pyathy VS Code
136
+ extension uses it). Details and sample output: [docs/check.md](https://github.com/bluemihai/pyathy/blob/main/docs/check.md).
137
+
138
+ ## A first feature
139
+
140
+ ```gherkin
141
+ Feature: Tic Tac Toe
142
+
143
+ Scenario: X wins with the top row
144
+ When I input 1, 4, 2, 5, 3
145
+ Then "Player X wins!" is printed
146
+ And the program asks "Play again? (y/n)"
147
+ ```
148
+
149
+ A `Scenario` is one run of the program, from a fresh start. `When` lines act (type answers,
150
+ roll dice) and `Then` lines check what the program did; `And` continues the line before it.
151
+
152
+ ## Built-in steps, or your own
153
+
154
+ The built-in steps are the keyboard and the screen: type an answer, make the die show a
155
+ face, check what was printed, check a file. They need no code, so a feature can be read and
156
+ written by someone who has never seen a test; `examples/tictactoe` uses nothing else.
157
+ Your own steps speak the program's own language instead (`Ann has $1440`, `Ann owns
158
+ Harbour`): a few lines of Python each, in a `features/*_steps.py`, worth writing once a feature
159
+ file starts repeating the same five built-in lines to say one thing.
160
+
161
+ Each built-in works after `Given`, `When`, `Then`, `And` or `But`. Text checks ignore case and
162
+ trailing spaces. Colours in the program's output (`\033[31m`-style codes) are ignored when
163
+ matching, and shown in the report. `python pyathy steps` prints this list (colour-coded on
164
+ a terminal: the parts you replace in cyan).
165
+
166
+ Each step has its own page under [`docs/`](https://github.com/bluemihai/pyathy/blob/main/docs/README.md), with what it checks, when it is
167
+ needed, a scenario that runs and the message it fails with. Two guides: [turn-based
168
+ games](https://github.com/bluemihai/pyathy/blob/main/docs/turns.md) (`red rolls 6`, `red moves from 0 to 3`) and [starting from a saved
169
+ state](https://github.com/bluemihai/pyathy/blob/main/docs/saved-games.md) (`a saved game:`, `the program is started again`).
170
+
171
+ | Step | What it does |
172
+ |---|---|
173
+ | [`I start the program`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/start-the-program.md) / [`I run the program with puzzle.txt --hard`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/start-the-program.md) | run `main.py` until it asks something or ends; `with …` starts it with these command-line arguments |
174
+ | [`the program other.py`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-program-other-py.md) | run `other.py` instead of `main.py` |
175
+ | [`the program may take 30 seconds`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-program-may-take.md) | wait longer for a slow program (default 10) |
176
+ | [`main.py has DEBUG = True`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/file-has-constant.md) | before it starts, set `DEBUG = …` at the top of `main.py` to this Python value (in the copy; your file stays as it is) |
177
+ | [`main.py has a DEBUG setting`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/file-has-setting.md) | `main.py` has `DEBUG = …` at the top, outside any function (only checks it is there; sets nothing) |
178
+ | [`I input 4`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/i-input.md) / [`I input 4, left, no`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/i-input.md) | type answers, one per question |
179
+ | [`I input enter`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/i-input.md) / [`I input enter, q`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/i-input.md) | press enter, on its own or as one answer of the list (quote `"enter"` to type the word) |
180
+ | [`I roll 6`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/i-roll.md) / [`I roll 3 and 4`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/i-roll.md) | the next dice show these faces |
181
+ | [`the random choice is red`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-random-choice-is.md) | the next random pick returns this value |
182
+ | [`the dice show 2, 4, 1`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-dice-show.md) | a line printed has these faces in this order, any separators but digits between them (`2 4 1`, `[2, 4, 1]`), no digit right next to them |
183
+ | [`red rolls 6`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/rolls.md) / [`Ann rolls 4+6`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/rolls.md) | `I input enter` (if the program is waiting for it) then `I roll 6`, after checking it is red's turn: the last line announcing a turn names red and no other player, without digits (`Player red:`) |
184
+ | [`red rolls 3 and picks 2`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/rolls-and-picks.md) / [`… and answers 2`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/rolls-and-picks.md) | the same, then types 2 at the question that follows |
185
+ | [`these turns are played 3 times:`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/these-turns-are-played.md) + a table | one step per row (`\| red rolls 5 \|`), run in order, that many times |
186
+ | [`the players are red and green`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-players-are.md) | the names a turn announcement may use (otherwise: the names typed or rolled for so far) |
187
+ | [`red's turn is announced`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/turn-is-announced.md) / [`it is red's turn`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/turn-is-announced.md) | a line names red and no other player, without digits |
188
+ | [`a pawn moves from 0 to 3`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/moves-from-to.md) / [`red moves from 0 to 3`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/moves-from-to.md) | a line of this turn (since the last roll) has these two numbers, `to` or an arrow between them |
189
+ | [`nothing moves`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/nothing-moves.md) | no such line this turn |
190
+ | [`Kim is named the winner`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/is-named-the-winner.md) | a line printed names Kim, and no other player, and has won, wins, winner or win (case ignored) |
191
+ | [`"Hello" is printed`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/is-printed.md) | somewhere in the output |
192
+ | [`"Error" is printed 3 times`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/is-printed-n-times.md) | exactly that many times |
193
+ | [`"Game over" is not printed`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/is-not-printed.md) | nowhere in the output |
194
+ | [`the output starts with "Welcome"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-output-starts-with.md) | the very first output |
195
+ | [`the output shows:`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-output-shows.md) + lines between `"""` | these lines, in a row |
196
+ | [`the line with "Total" also has "42"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-line-with-also-has.md) | the last line printed with Total in it also has 42 |
197
+ | [`the "Bob" row has "7" under "Score"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-row-has-under.md) / [`… has nothing under "Score"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-row-has-under.md) | in the last table printed with a Score column (cells split by `│` or `\|`; tables lined up with spaces are not read), Bob's row has 7 there, or nothing |
198
+ | [`the program asks "Your name?"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-program-asks.md) | it is now waiting for input after that question |
199
+ | [`"orange" is refused with a message`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/is-refused-with-a-message.md) | after typing it, a message was printed and the same question was asked again (a menu printed every time is not the message; `""` is pressing enter) |
200
+ | [`the program ends`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-program-ends.md) / [`the program is still running`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-program-is-still-running.md) | |
201
+ | [`a file "photos/beach.jpg"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/a-file.md) | an empty file in the folder before the program starts (its folders made too) |
202
+ | [`a file "game.txt" containing "round 3"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/a-file-containing.md) | put this one-line file in the folder before the program starts |
203
+ | [`a file "game.txt" with:`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/a-file-with.md) + lines between `"""` | the same, several lines |
204
+ | [`there is no file "game.txt"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/there-is-no-file.md) | the program starts without it, whatever is in your folder (a saved game from playing, say) |
205
+ | [`a file "game.txt" is written`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/a-file-is-written.md) / [`no file is written`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/no-file-is-written.md) | the program made a file, or changed one |
206
+ | [`the file "game.txt" contains "round 4"`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-file-contains.md) | anywhere in the file |
207
+ | [`the file "game.txt" contains:`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-file-contains-lines.md) + lines between `"""` | these lines, in a row |
208
+ | [`a saved game:`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/a-saved-game.md) + lines between `"""` | these lines are in the program's save file before it starts |
209
+ | [`there is no saved game`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/there-is-no-saved-game.md) | the program starts without its save file |
210
+ | [`a saved game is written`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/a-saved-game-is-written.md) | the program made its save file, or changed it |
211
+ | [`the saved game holds:`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-saved-game-holds.md) + lines between `"""` | these lines, in a row, in the save file |
212
+ | [`no saved game is left`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/no-saved-game-is-left.md) | the save file was removed, or emptied |
213
+ | [`the program is started again`](https://github.com/bluemihai/pyathy/blob/main/docs/steps/the-program-is-started-again.md) | stop it and start it over in the same folder, so the files it wrote are still there |
214
+
215
+ ## Your own steps
216
+
217
+ Every `*_steps.py` next to the `.feature` files is loaded. A step is a pattern in
218
+ [Cucumber style](https://github.com/cucumber/cucumber-expressions): `{name}` matches anything,
219
+ `{name:w}` one word, `{n:d}` a whole number, and each field becomes a parameter of the function.
220
+ `program.settle()` returns everything printed so far; `fail(program, message)` fails the step
221
+ with the program's last lines under the message.
222
+ `examples/monopoly/features/monopoly_steps.py` adds `Ann has $1460` and `Ann owns Harbour`:
223
+
224
+ ```python
225
+ from pyathy.steps import fail, step
226
+
227
+ @step("{name:w} has ${cash:d}")
228
+ def has(program, name, cash):
229
+ ...
230
+ ```
231
+
232
+ `python pyathy steps` lists them under the built-ins, as written. The whole of it, with the
233
+ step above in full: [docs/own-steps.md](https://github.com/bluemihai/pyathy/blob/main/docs/own-steps.md).
234
+
235
+ ## Pull an assignment's features
236
+
237
+ In a folder `lms grade` opened, `_node` links to the assignment in the curriculum and `_solution`
238
+ to its `solutionN/`. Next to `solutionN/` and `templateN/`, the curriculum keeps `featuresN/`:
239
+
240
+ ```
241
+ pyathy pull copy <_node>/featuresN/ into features/ (N from the _solution link)
242
+ pyathy run features/
243
+ ```
244
+
245
+ A pull into a folder that already has `features/` is refused unless `--force`.
246
+
247
+ Every pull, from the curriculum or a locked file, leaves one line in `features/pulled.txt`: when,
248
+ by which pyathy, what it pulled, and a fingerprint of the files (12 characters of their sha256;
249
+ the same files give the same fingerprint, wherever they came from):
250
+
251
+ ```
252
+ pulled 2026-11-16 10:12 by pyathy 0.1.21: features2/ of lists at curriculum commit 4fd3e58, fingerprint 2f61c0e9a4b8
253
+ pulled 2026-11-16 10:12 by pyathy 0.1.21: variant 2 of python-exam, locked 2026-11-02 09:40 by pyathy 0.1.21, fingerprint 7b3d70192511
254
+ ```
255
+
256
+ The curriculum commit is the last one that touched `featuresN/` (`plus uncommitted changes` when
257
+ the folder differs from it; left out when the curriculum is not a git checkout). A pull `--force`
258
+ replaces `features/` and the note with it. A plain `pyathy` ignores the note.
259
+
260
+ ## Exams: lock and pull
261
+
262
+ An exam's features are not handed out; they stay in one password-locked file per exam,
263
+ holding every variant. The teacher who writes the exam locks it once:
264
+
265
+ ```
266
+ pyathy lock python-exam variants/ variants/ holds 1/, 2/, … each with its .feature and *steps.py files
267
+ ```
268
+
269
+ It asks the password twice and writes `python-exam.pyathy-locked` into the store: the folder
270
+ `$PYATHY_STORE`, or `~/.pyathy/locked/` when that is not set. An existing file is overwritten only
271
+ after a yes, or with `--force`. Colleagues who grade get a copy of that file and the password.
272
+
273
+ When the store is a git repo (a clone the teachers share), pyathy keeps it fresh: `pyathy lock`
274
+ commits the file it wrote ("lock <node>") and pushes, and `pyathy pull` runs `git pull --ff-only`
275
+ first. When git fails (offline, no remote), one `pyathy: warning:` line says so and the local copy
276
+ is used; a lock stays committed and goes up with the next push.
277
+
278
+ In the folder a grading tool opened for one attempt, named like `student@python-exam~1` (the exam
279
+ is read from the part between `@` and `~`):
280
+
281
+ ```
282
+ pyathy pull list the exam's variant numbers (no password needed)
283
+ pyathy pull 2 ask the password, put variant 2's files into features/
284
+ pyathy run features/
285
+ ```
286
+
287
+ A pull into a folder that already has `features/` is refused unless `--force`, which replaces the
288
+ whole `features/` folder.
289
+ For scripts, the password may come from `$PYATHY_PASSWORD`; it is never printed.
290
+
291
+ The locked file carries a stamp, readable without the password: when it was locked, by which
292
+ pyathy, and each variant's fingerprint. `pyathy lock` and a `pyathy pull` without a number print it:
293
+
294
+ ```
295
+ locked 2026-11-02 09:40 by pyathy 0.1.21; fingerprints 1: cd663cb8515c, 2: 7b3d70192511
296
+ ```
297
+
298
+ A file locked before the stamp (pyathy 0.1.20 and earlier) has none and still pulls.
299
+
300
+ What the lock does: without the password, the file shows only how many variants there are,
301
+ their numbers and the stamp; changing the stamp makes the file read as damaged; a wrong password or a damaged file is refused (`wrong password or damaged file`)
302
+ before anything is written. It uses Python's standard library only (scrypt for the key, an
303
+ HMAC-SHA256 keystream, an HMAC-SHA256 tag), so nothing needs installing.
304
+ What it does not do: once pulled, the files are plain text in that folder, readable by anyone who
305
+ can read the folder; and anyone with the password and the file can read every variant. Keep the
306
+ password with the people who grade, and remove `features/` when grading is done if the folder
307
+ travels further.
308
+
309
+ ## Examples
310
+
311
+ `examples/tictactoe` (built-in steps only), `examples/sudoku` (boards checked with
312
+ `the output shows:`, a puzzle file as argument) and `examples/monopoly` (dice and its own
313
+ steps). `examples/edge` fails on purpose, to show the messages. Run them all with
314
+ `scripts/try-examples.sh`.
315
+
316
+ ## License
317
+
318
+ MIT, see `LICENSE`.
@@ -0,0 +1,287 @@
1
+ # pyathy
2
+
3
+ Test a Python command-line program with scenarios written in plain English.
4
+
5
+ You write `.feature` files (Gherkin: `Scenario`, `When`, `Then`) that type answers into
6
+ the program, fix its dice rolls, and check what it prints. pyathy runs each scenario against
7
+ a fresh start of `main.py` and shows each run, then one `✔`/`✘` line per scenario plus a total.
8
+ It is built on [pytest-bdd](https://github.com/pytest-dev/pytest-bdd) and needs Python 3.11+.
9
+
10
+ It was built for the Saxion ADSD python course, so that the acceptance tests of an assignment
11
+ can be read, and written, by people new to programming: the steps are the words a person
12
+ would use at the keyboard, and no code is needed. It tests any Python command-line program,
13
+ anywhere, the same way.
14
+
15
+ Ruby has this layer already: [Aruba](https://github.com/cucumber/aruba) gives Cucumber
16
+ ready-made steps for command-line programs (run it, type this, expect that output). Python's
17
+ pytest-bdd has no such layer; pyathy is that layer for Python.
18
+
19
+ ## Install and use
20
+
21
+ Four ways to get the command. They run the same features the same way.
22
+
23
+ **From PyPI**, as a command on your PATH:
24
+
25
+ ```
26
+ pipx install pyathy # or: uv tool install pyathy
27
+ ```
28
+
29
+ or inside a project's venv: `pip install pyathy`. For VS Code there is the pyathy extension,
30
+ `MB42.pyathy` in the Marketplace.
31
+
32
+ **No install: the `pyathy/` folder next to `main.py`.** The folder is built from this repo by
33
+ `scripts/build-folder.sh` into `dist/pyathy/`, with pytest-bdd inside, so nothing needs installing:
34
+
35
+ ```
36
+ my-game/
37
+ main.py
38
+ features/
39
+ game.feature
40
+ pyathy/
41
+ ```
42
+
43
+ ```
44
+ python pyathy
45
+ ```
46
+
47
+ In a course, an assignment's package is this folder plus its `features/`, zipped.
48
+
49
+ **Poetry**, with that same `pyathy/` folder in the project:
50
+
51
+ ```
52
+ poetry add ./pyathy
53
+ poetry run pyathy
54
+ ```
55
+
56
+ **pip**, in a venv: `pip install ./pyathy` for the folder, or from a clone of this repo:
57
+
58
+ ```
59
+ python -m venv .venv
60
+ .venv/bin/pip install . # Windows: .venv\Scripts\pip install .
61
+ cd examples/tictactoe
62
+ ../../.venv/bin/pyathy # Windows: ..\..\.venv\Scripts\pyathy
63
+ ```
64
+
65
+ That runs the tic-tac-toe example's features against its `main.py`.
66
+
67
+ From the folder that holds `main.py` and `features/` (write `python pyathy …` for the folder,
68
+ `poetry run pyathy …` under Poetry):
69
+
70
+ ```
71
+ pyathy run every features/*.feature against main.py
72
+ pyathy features/x.feature run only that file (or folder)
73
+ pyathy check find mistakes in the feature files, without running main.py
74
+ pyathy init create features/hello.feature (and a main.py) to start from
75
+ pyathy steps every step you can use (plus your own, from features/*_steps.py)
76
+ pyathy -h usage and an example feature
77
+ ```
78
+
79
+ Options, each with a short and a long form:
80
+
81
+ ```
82
+ -q, --quiet only one line per scenario (a ✘ gets one reason line) and the total
83
+ -ff, --fail-fast stop at the first scenario that fails
84
+ -nf, --next-failure run the scenarios that failed last time, in order, stopping at the first that still fails
85
+ -s, --solution [FOLDER] run the features here against ./_solution/main.py, or ./FOLDER/main.py (-s obj2 means _solution-obj2)
86
+ -o, --output show|hide|slow the program's output in the report: show it (the default), hide it, or slow: a line at a time, to read along (on a terminal only)
87
+ --delay SECONDS the pause after each line under -o slow (default 0.1: a 100-line run takes 10 seconds; --delay alone means -o slow)
88
+ -h, --help this help
89
+ -v, --version pyathy's version and where it runs from
90
+ ```
91
+
92
+ The report shows each scenario's run as a terminal would have (what was printed, what was
93
+ typed), then its `✔`/`✘` line with the reason under a `✘`, a summary per feature, and the last
94
+ line `TOTAL n of m`; `-q` keeps only the `✔`/`✘` lines and the total. Every report ends with
95
+ `pyathy <version> · <where it runs from>`, the same as `-v`, so two copies on one machine are
96
+ never confused. `-nf` reads the failures remembered in `.pyathy/last-run.json`; `-s` is for
97
+ the teacher's folder, where the reference program sits in `_solution/`. The report's colours,
98
+ the long-run cut and the details of `-nf` and `-s`: [docs/running.md](docs/running.md).
99
+
100
+ `pyathy check` reads the feature files without running the program and lists, per file,
101
+ what would stop a scenario before it starts: a line no step matches (with the closest step,
102
+ `did you mean: I input Ada`), a file that is not valid Gherkin, a scenario or step indented
103
+ differently from the others, and a file step pyathy cannot find in the program. It exits with
104
+ 1 when it found something; `--json` prints the same for an editor (the pyathy VS Code
105
+ extension uses it). Details and sample output: [docs/check.md](docs/check.md).
106
+
107
+ ## A first feature
108
+
109
+ ```gherkin
110
+ Feature: Tic Tac Toe
111
+
112
+ Scenario: X wins with the top row
113
+ When I input 1, 4, 2, 5, 3
114
+ Then "Player X wins!" is printed
115
+ And the program asks "Play again? (y/n)"
116
+ ```
117
+
118
+ A `Scenario` is one run of the program, from a fresh start. `When` lines act (type answers,
119
+ roll dice) and `Then` lines check what the program did; `And` continues the line before it.
120
+
121
+ ## Built-in steps, or your own
122
+
123
+ The built-in steps are the keyboard and the screen: type an answer, make the die show a
124
+ face, check what was printed, check a file. They need no code, so a feature can be read and
125
+ written by someone who has never seen a test; `examples/tictactoe` uses nothing else.
126
+ Your own steps speak the program's own language instead (`Ann has $1440`, `Ann owns
127
+ Harbour`): a few lines of Python each, in a `features/*_steps.py`, worth writing once a feature
128
+ file starts repeating the same five built-in lines to say one thing.
129
+
130
+ Each built-in works after `Given`, `When`, `Then`, `And` or `But`. Text checks ignore case and
131
+ trailing spaces. Colours in the program's output (`\033[31m`-style codes) are ignored when
132
+ matching, and shown in the report. `python pyathy steps` prints this list (colour-coded on
133
+ a terminal: the parts you replace in cyan).
134
+
135
+ Each step has its own page under [`docs/`](docs/README.md), with what it checks, when it is
136
+ needed, a scenario that runs and the message it fails with. Two guides: [turn-based
137
+ games](docs/turns.md) (`red rolls 6`, `red moves from 0 to 3`) and [starting from a saved
138
+ state](docs/saved-games.md) (`a saved game:`, `the program is started again`).
139
+
140
+ | Step | What it does |
141
+ |---|---|
142
+ | [`I start the program`](docs/steps/start-the-program.md) / [`I run the program with puzzle.txt --hard`](docs/steps/start-the-program.md) | run `main.py` until it asks something or ends; `with …` starts it with these command-line arguments |
143
+ | [`the program other.py`](docs/steps/the-program-other-py.md) | run `other.py` instead of `main.py` |
144
+ | [`the program may take 30 seconds`](docs/steps/the-program-may-take.md) | wait longer for a slow program (default 10) |
145
+ | [`main.py has DEBUG = True`](docs/steps/file-has-constant.md) | before it starts, set `DEBUG = …` at the top of `main.py` to this Python value (in the copy; your file stays as it is) |
146
+ | [`main.py has a DEBUG setting`](docs/steps/file-has-setting.md) | `main.py` has `DEBUG = …` at the top, outside any function (only checks it is there; sets nothing) |
147
+ | [`I input 4`](docs/steps/i-input.md) / [`I input 4, left, no`](docs/steps/i-input.md) | type answers, one per question |
148
+ | [`I input enter`](docs/steps/i-input.md) / [`I input enter, q`](docs/steps/i-input.md) | press enter, on its own or as one answer of the list (quote `"enter"` to type the word) |
149
+ | [`I roll 6`](docs/steps/i-roll.md) / [`I roll 3 and 4`](docs/steps/i-roll.md) | the next dice show these faces |
150
+ | [`the random choice is red`](docs/steps/the-random-choice-is.md) | the next random pick returns this value |
151
+ | [`the dice show 2, 4, 1`](docs/steps/the-dice-show.md) | a line printed has these faces in this order, any separators but digits between them (`2 4 1`, `[2, 4, 1]`), no digit right next to them |
152
+ | [`red rolls 6`](docs/steps/rolls.md) / [`Ann rolls 4+6`](docs/steps/rolls.md) | `I input enter` (if the program is waiting for it) then `I roll 6`, after checking it is red's turn: the last line announcing a turn names red and no other player, without digits (`Player red:`) |
153
+ | [`red rolls 3 and picks 2`](docs/steps/rolls-and-picks.md) / [`… and answers 2`](docs/steps/rolls-and-picks.md) | the same, then types 2 at the question that follows |
154
+ | [`these turns are played 3 times:`](docs/steps/these-turns-are-played.md) + a table | one step per row (`\| red rolls 5 \|`), run in order, that many times |
155
+ | [`the players are red and green`](docs/steps/the-players-are.md) | the names a turn announcement may use (otherwise: the names typed or rolled for so far) |
156
+ | [`red's turn is announced`](docs/steps/turn-is-announced.md) / [`it is red's turn`](docs/steps/turn-is-announced.md) | a line names red and no other player, without digits |
157
+ | [`a pawn moves from 0 to 3`](docs/steps/moves-from-to.md) / [`red moves from 0 to 3`](docs/steps/moves-from-to.md) | a line of this turn (since the last roll) has these two numbers, `to` or an arrow between them |
158
+ | [`nothing moves`](docs/steps/nothing-moves.md) | no such line this turn |
159
+ | [`Kim is named the winner`](docs/steps/is-named-the-winner.md) | a line printed names Kim, and no other player, and has won, wins, winner or win (case ignored) |
160
+ | [`"Hello" is printed`](docs/steps/is-printed.md) | somewhere in the output |
161
+ | [`"Error" is printed 3 times`](docs/steps/is-printed-n-times.md) | exactly that many times |
162
+ | [`"Game over" is not printed`](docs/steps/is-not-printed.md) | nowhere in the output |
163
+ | [`the output starts with "Welcome"`](docs/steps/the-output-starts-with.md) | the very first output |
164
+ | [`the output shows:`](docs/steps/the-output-shows.md) + lines between `"""` | these lines, in a row |
165
+ | [`the line with "Total" also has "42"`](docs/steps/the-line-with-also-has.md) | the last line printed with Total in it also has 42 |
166
+ | [`the "Bob" row has "7" under "Score"`](docs/steps/the-row-has-under.md) / [`… has nothing under "Score"`](docs/steps/the-row-has-under.md) | in the last table printed with a Score column (cells split by `│` or `\|`; tables lined up with spaces are not read), Bob's row has 7 there, or nothing |
167
+ | [`the program asks "Your name?"`](docs/steps/the-program-asks.md) | it is now waiting for input after that question |
168
+ | [`"orange" is refused with a message`](docs/steps/is-refused-with-a-message.md) | after typing it, a message was printed and the same question was asked again (a menu printed every time is not the message; `""` is pressing enter) |
169
+ | [`the program ends`](docs/steps/the-program-ends.md) / [`the program is still running`](docs/steps/the-program-is-still-running.md) | |
170
+ | [`a file "photos/beach.jpg"`](docs/steps/a-file.md) | an empty file in the folder before the program starts (its folders made too) |
171
+ | [`a file "game.txt" containing "round 3"`](docs/steps/a-file-containing.md) | put this one-line file in the folder before the program starts |
172
+ | [`a file "game.txt" with:`](docs/steps/a-file-with.md) + lines between `"""` | the same, several lines |
173
+ | [`there is no file "game.txt"`](docs/steps/there-is-no-file.md) | the program starts without it, whatever is in your folder (a saved game from playing, say) |
174
+ | [`a file "game.txt" is written`](docs/steps/a-file-is-written.md) / [`no file is written`](docs/steps/no-file-is-written.md) | the program made a file, or changed one |
175
+ | [`the file "game.txt" contains "round 4"`](docs/steps/the-file-contains.md) | anywhere in the file |
176
+ | [`the file "game.txt" contains:`](docs/steps/the-file-contains-lines.md) + lines between `"""` | these lines, in a row |
177
+ | [`a saved game:`](docs/steps/a-saved-game.md) + lines between `"""` | these lines are in the program's save file before it starts |
178
+ | [`there is no saved game`](docs/steps/there-is-no-saved-game.md) | the program starts without its save file |
179
+ | [`a saved game is written`](docs/steps/a-saved-game-is-written.md) | the program made its save file, or changed it |
180
+ | [`the saved game holds:`](docs/steps/the-saved-game-holds.md) + lines between `"""` | these lines, in a row, in the save file |
181
+ | [`no saved game is left`](docs/steps/no-saved-game-is-left.md) | the save file was removed, or emptied |
182
+ | [`the program is started again`](docs/steps/the-program-is-started-again.md) | stop it and start it over in the same folder, so the files it wrote are still there |
183
+
184
+ ## Your own steps
185
+
186
+ Every `*_steps.py` next to the `.feature` files is loaded. A step is a pattern in
187
+ [Cucumber style](https://github.com/cucumber/cucumber-expressions): `{name}` matches anything,
188
+ `{name:w}` one word, `{n:d}` a whole number, and each field becomes a parameter of the function.
189
+ `program.settle()` returns everything printed so far; `fail(program, message)` fails the step
190
+ with the program's last lines under the message.
191
+ `examples/monopoly/features/monopoly_steps.py` adds `Ann has $1460` and `Ann owns Harbour`:
192
+
193
+ ```python
194
+ from pyathy.steps import fail, step
195
+
196
+ @step("{name:w} has ${cash:d}")
197
+ def has(program, name, cash):
198
+ ...
199
+ ```
200
+
201
+ `python pyathy steps` lists them under the built-ins, as written. The whole of it, with the
202
+ step above in full: [docs/own-steps.md](docs/own-steps.md).
203
+
204
+ ## Pull an assignment's features
205
+
206
+ In a folder `lms grade` opened, `_node` links to the assignment in the curriculum and `_solution`
207
+ to its `solutionN/`. Next to `solutionN/` and `templateN/`, the curriculum keeps `featuresN/`:
208
+
209
+ ```
210
+ pyathy pull copy <_node>/featuresN/ into features/ (N from the _solution link)
211
+ pyathy run features/
212
+ ```
213
+
214
+ A pull into a folder that already has `features/` is refused unless `--force`.
215
+
216
+ Every pull, from the curriculum or a locked file, leaves one line in `features/pulled.txt`: when,
217
+ by which pyathy, what it pulled, and a fingerprint of the files (12 characters of their sha256;
218
+ the same files give the same fingerprint, wherever they came from):
219
+
220
+ ```
221
+ pulled 2026-11-16 10:12 by pyathy 0.1.21: features2/ of lists at curriculum commit 4fd3e58, fingerprint 2f61c0e9a4b8
222
+ pulled 2026-11-16 10:12 by pyathy 0.1.21: variant 2 of python-exam, locked 2026-11-02 09:40 by pyathy 0.1.21, fingerprint 7b3d70192511
223
+ ```
224
+
225
+ The curriculum commit is the last one that touched `featuresN/` (`plus uncommitted changes` when
226
+ the folder differs from it; left out when the curriculum is not a git checkout). A pull `--force`
227
+ replaces `features/` and the note with it. A plain `pyathy` ignores the note.
228
+
229
+ ## Exams: lock and pull
230
+
231
+ An exam's features are not handed out; they stay in one password-locked file per exam,
232
+ holding every variant. The teacher who writes the exam locks it once:
233
+
234
+ ```
235
+ pyathy lock python-exam variants/ variants/ holds 1/, 2/, … each with its .feature and *steps.py files
236
+ ```
237
+
238
+ It asks the password twice and writes `python-exam.pyathy-locked` into the store: the folder
239
+ `$PYATHY_STORE`, or `~/.pyathy/locked/` when that is not set. An existing file is overwritten only
240
+ after a yes, or with `--force`. Colleagues who grade get a copy of that file and the password.
241
+
242
+ When the store is a git repo (a clone the teachers share), pyathy keeps it fresh: `pyathy lock`
243
+ commits the file it wrote ("lock <node>") and pushes, and `pyathy pull` runs `git pull --ff-only`
244
+ first. When git fails (offline, no remote), one `pyathy: warning:` line says so and the local copy
245
+ is used; a lock stays committed and goes up with the next push.
246
+
247
+ In the folder a grading tool opened for one attempt, named like `student@python-exam~1` (the exam
248
+ is read from the part between `@` and `~`):
249
+
250
+ ```
251
+ pyathy pull list the exam's variant numbers (no password needed)
252
+ pyathy pull 2 ask the password, put variant 2's files into features/
253
+ pyathy run features/
254
+ ```
255
+
256
+ A pull into a folder that already has `features/` is refused unless `--force`, which replaces the
257
+ whole `features/` folder.
258
+ For scripts, the password may come from `$PYATHY_PASSWORD`; it is never printed.
259
+
260
+ The locked file carries a stamp, readable without the password: when it was locked, by which
261
+ pyathy, and each variant's fingerprint. `pyathy lock` and a `pyathy pull` without a number print it:
262
+
263
+ ```
264
+ locked 2026-11-02 09:40 by pyathy 0.1.21; fingerprints 1: cd663cb8515c, 2: 7b3d70192511
265
+ ```
266
+
267
+ A file locked before the stamp (pyathy 0.1.20 and earlier) has none and still pulls.
268
+
269
+ What the lock does: without the password, the file shows only how many variants there are,
270
+ their numbers and the stamp; changing the stamp makes the file read as damaged; a wrong password or a damaged file is refused (`wrong password or damaged file`)
271
+ before anything is written. It uses Python's standard library only (scrypt for the key, an
272
+ HMAC-SHA256 keystream, an HMAC-SHA256 tag), so nothing needs installing.
273
+ What it does not do: once pulled, the files are plain text in that folder, readable by anyone who
274
+ can read the folder; and anyone with the password and the file can read every variant. Keep the
275
+ password with the people who grade, and remove `features/` when grading is done if the folder
276
+ travels further.
277
+
278
+ ## Examples
279
+
280
+ `examples/tictactoe` (built-in steps only), `examples/sudoku` (boards checked with
281
+ `the output shows:`, a puzzle file as argument) and `examples/monopoly` (dice and its own
282
+ steps). `examples/edge` fails on purpose, to show the messages. Run them all with
283
+ `scripts/try-examples.sh`.
284
+
285
+ ## License
286
+
287
+ MIT, see `LICENSE`.
@@ -0,0 +1 @@
1
+ __version__ = "0.1.22"