Testing¶
A program that draws on a terminal is hard to test on a terminal. With xnano
you do not need one. xnano.new() makes a canvas in memory that has the same
screen, keyboard, mouse and clock as a live terminal. A test writes on it,
presses its keys, moves its clock, and reads what it shows.
These examples use pytest, but any test tool works.
Write a program that you can test¶
Put the code that builds the screen in a function that takes a canvas. The program gives it a live terminal, and a test gives it a canvas in memory.
import xnano
def build(canvas: xnano.Canvas) -> None:
counter = canvas.write('count 0')
canvas.write('space add · q quit', y='bottom', dim=True)
count = 0
@canvas.hook(on='key', keys='space')
def add(context: xnano.Context):
nonlocal count
count += 1
counter.text = f'count {count}'
if count == 3:
counter.color.fg = 'green'
if __name__ == '__main__':
with xnano.open(height=3) as terminal: # >> [live]
build(terminal)
terminal.run(stop_on='q')
A terminal is a canvas, so build() takes it. A test calls build() with a
canvas from xnano.new().
Read the screen¶
canvas.render() returns the screen as text, one line for each row. Compare it
with the text that you expect.
import xnano
def build(canvas: xnano.Canvas) -> None:
canvas.write('count 0')
canvas.write('space add · q quit', y='bottom', dim=True)
def test_the_counter_starts_at_zero():
with xnano.new(width=24, height=3) as canvas: # >> [size]
build(canvas)
lines = canvas.render().splitlines()
assert lines[0] == 'count 0'
assert lines[2] == 'space add · q quit'
test_the_counter_starts_at_zero()
Give the canvas the size of the window that you want to test. To test a small window, make a small canvas.
render() gives the characters without their colors. To test a color, read the
placement, for example counter.color.fg, or use canvas.render(format='ansi').
Press keys¶
canvas.push() gives the canvas an event, and canvas.deliver_events() runs
the hooks that hear it. Event makes the events: a key
press, a mouse press, pasted text, or an event of your own.
import xnano
from xnano.events import Event
with xnano.new(width=24, height=3) as canvas:
counter = canvas.write('count 0')
@canvas.hook(on='key', keys='space')
def add(context: xnano.Context):
counter.text = f'count {int(counter.text.split()[1]) + 1}'
for _ in range(3):
canvas.push(Event.key_press('space')) # >> [push]
canvas.deliver_events() # >> [deliver]
assert counter.text == 'count 3'
Adds a press of the space bar. The hooks do not run yet.
Runs the hooks for all the events that you pushed. It does not move the clock.
Move the clock¶
A canvas from xnano.new() has a clock that moves only when you move it. A
test of a timer or an effect does not wait: it tells the clock how much time
passes. canvas.clock.sleep(seconds) moves the clock one frame at a time, and
the timers and effects in that time run. canvas.clock.step() moves one frame.
import xnano
with xnano.new(width=24, height=1) as canvas:
label = canvas.write('0 s')
@canvas.hook(on='tick', every=1.0)
def count_up(context: xnano.Context):
label.text = f'{round(context.clock.elapsed_seconds)} s'
canvas.clock.sleep(3) # >> [sleep]
assert canvas.render() == '3 s'
Three seconds pass on the clock of the canvas, and the test does not wait.
Sound shows how to test a program that plays sound.