Chrono MockReferencia de la línea de comandos
Todas las opciones de ambos comandos, las dos tablas de códigos de salida y cómo leer lo que devuelve. La versión narrativa, con el razonamiento, está en la página CLI y CI.
Dos comandos
chrono run inicia una aplicación en otra fecha y hora. chrono calc
calcula una fecha y te dice qué la hace interesante. Comparten una misma gramática de pasos, así
que un desplazamiento escrito para uno significa lo mismo en el otro.
chrono version responde a una tercera pregunta, mucho más pequeña: qué compilación es,
cuál de los dos núcleos es el ejecutable y qué versión del protocolo habla. Una línea en la salida
estándar, para que un script pueda capturarla.
chrono license responde a la cuarta: bajo qué licencia se distribuye esta
compilación, el descargo de garantía y los componentes de terceros enlazados en ella.
También dice dónde están en el disco el texto completo de la licencia y los avisos de
terceros, o admite que la copia que ejecutas no los tiene a su lado.
--components lista cada componente incluido con su versión, en lugar de un
resumen.
chrono presets lista el catálogo de escenarios tal como lo lee
--preset: cada escenario de la carpeta, escrito con las palabras que lee la
gramática de la calculadora, y cada archivo que rechazaría, con el motivo.
--json escribe chronomock.presets/1 y --dir indica
otra carpeta.
chrono run <target> [options] chrono calc [options] chrono version # chrono 0.4.0 (x64, protocol 1) chrono license # GPL-3.0-only, and what is bundled chrono presets # el catálogo, tal como lo lee --preset chrono --help # usage for all of them
chrono run - opciones
| Opción | Qué hace |
|---|---|
--at <moment> |
El momento en el que empezar, en la zona de la sesión. Absoluto
(2038-01-19T03:14:07) o relativo con un signo inicial
(+1d, -2h). Unidades: s m h d w mo q y -
m son minutos y mo son meses. Sin esta opción, el
reloj de la sesión arranca en la hora real actual, de modo que --mode xN por sí
solo simplemente hace correr más rápido al objetivo. |
--zone +HH:MM |
La zona de la sesión: la zona en la que se escribe el momento y la que informan las llamadas de hora local del objetivo. Un desfase fijo, sin horario de verano. Sin ella, la zona propia del equipo. |
--mode flow|frozen|xN |
flow corre a velocidad real, frozen detiene el reloj,
xN lo hace correr N veces más rápido (x60 convierte una hora en un
minuto, x1440 un día). |
--scale-duration |
Acelerar también el eje del tiempo transcurrido: contadores de ticks, tiempo de interrupción, pausas y temporizadores. Las esperas sobre objetos se cuentan y conservan su duración real. Desactivado por defecto, porque un reloj de pared y un cronómetro son preguntas distintas. Un temporizador o un retardo fijado para una fecha y hora sigue el reloj de la sesión con o sin esta opción. |
--scale-qpc |
Escala también el contador de alta resolución, donde Python 3.13+ monotonic,
.NET Stopwatch y Java nanoTime leen el tiempo transcurrido.
Desactivado por defecto: una aplicación que mide su renderizado con ese contador puede verse
distorsionada. |
--ticks N |
Termina la sesión tras N latidos, de un segundo real cada uno, e informa. Sin ella, la herramienta sigue conectada hasta que el objetivo, y todo programa que este lanzó y que corra con el reloj de la sesión, hayan terminado - un lanzador que termina de inmediato deja la sesión a cargo de la aplicación que inició. |
--timeout <s> |
Se rinde tras esos segundos y sale con 6, para un pipeline que no debe colgarse. Con independencia de esta opción, un núcleo que no dice nada durante 15 segundos se detiene y también sale con 6 - en ambos casos la ejecución se corta, así que no lleva veredicto. |
--args "..." |
Argumentos para el objetivo, como una sola cadena, divididos con la misma regla que usa
Windows - así un argumento con espacios sobrevive. Para un objetivo Chromium,
--user-data-dir y --remote-debugging-port se rechazan en lugar de
sobrescribirse: la sesión necesita su propio perfil aislado, y ejecutar en silencio sobre tu
perfil real del navegador es lo único que no debe ocurrir. |
--cwd <dir> |
Inicia el objetivo en ese directorio. Sin ella, el objetivo hereda el nuestro, que es lo
que hacía toda ejecución antes de que existiera esta opción. Un valor vacío es un error de
uso y no «ningún directorio» - ausente y vacío son cosas distintas, y solo lo ausente es algo
que Windows puede recibir. Un directorio que no existe detiene la sesión con
target.cwd_missing antes de lanzar nada, en lugar de aparecer más tarde como un
objetivo que no quiso arrancar. |
--preset <id> |
Toma el momento y la velocidad de presets/<id>.json. Excluyente con
--at, --mode y --scale-duration, ya que el escenario
es entonces la única fuente de ambos. |
--param id=value |
Rellena un parámetro del escenario. Repetible, requiere --preset. Solo en
run, la fecha de inicio de una prueba toma por defecto la fecha de creación del
propio ejecutable objetivo, de modo que un escenario de prueba cuenta desde el día en que se
instaló la aplicación sin que lo escribas. |
--set-after T:M |
En el latido T, cambia la velocidad a M. En marcha, el multiplicador es al menos 1 - congelar en plena sesión no se ofrece aquí. |
--jump-after T:moment |
En el latido T, salta el reloj a ese momento, absoluto o relativo, en la zona de la sesión. |
--force |
Mantiene la sesión aunque el veredicto inicial diga que la sustitución no tuvo efecto - por defecto se detiene el objetivo, porque una sesión que no demostró nada es peor que ninguna sesión. El veredicto no cambia, ni el código de salida. Esto solo decide si el objetivo sigue ejecutándose. |
--no-embedded |
Deja las páginas web dentro de la aplicación (WebView2, Qt WebEngine) en el reloj real y no abre ningún puerto de depuración. Sin ella, la sesión pide a ese motor que abra un puerto local y pone sus páginas en el reloj de la sesión a través de él: mientras el puerto está abierto, cualquier otro programa de este equipo puede usarlo para llegar a esas páginas. |
--elevated-embedded |
Para una aplicación que se ejecuta como administrador, desde un Chrono Mock que
también se ejecuta como administrador. WebView2 ignora para una aplicación así el
ajuste por el que la sesión llega a sus páginas, de modo que la sesión escribe un
valor en el registro de la máquina (HKLM, con el nombre del .exe de la aplicación)
durante su duración y lo elimina al final. Mientras la aplicación se ejecuta,
cualquier otro programa de este equipo puede llegar a sus páginas por el puerto, y la
aplicación tiene derechos de administrador. No con --no-embedded. |
--keep-background-timers |
Inicia el motor web - el navegador de una aplicación Chromium o Electron, o el motor
dentro de una aplicación - con la ralentización de los temporizadores en ventanas
ocultas desactivada, de modo que una ventana minimizada conserva la velocidad de la
sesión. La aplicación también trabaja entonces a pleno ritmo mientras está oculta. Una
aplicación iniciada como administrador mediante --elevated-embedded no la
recibe. |
--dry-run |
Imprime lo que sería la sesión sin iniciar nada: el momento y la zona resueltos y de
dónde salieron, con qué rellenó un escenario cada parámetro, los argumentos tras
dividirlos y cuál de los dos mecanismos usaría el objetivo. No se inicia ningún
proceso ni se escribe ningún archivo, tampoco el que nombra --report.
Sale con 0 para un plan viable y con 2 para un objetivo que no existe, que es el
código que da una ejecución real ante el mismo hecho. Un plan no lleva veredicto y lo
dice - solo una sesión real lo tiene. Con --json el plan se da como
datos, incluidos session.elevated_embedded y
session.elevated_embedded_value, el nombre de archivo con el que se
nombraría el valor del registro cuando la opción se aplica a un destino
.exe, y null en otro caso. Un nombre ahí no es una promesa de escritura:
la sesión solo escribe el valor cuando el propio Chrono Mock se ejecuta como
administrador. |
--report <path> |
Escribe el informe para personas en un archivo. Un veredicto distinto de funciona abre ese archivo con un aviso de evidencia poco fiable, porque una evidencia que oculta su propia duda es peor que ninguna. Una sesión con veredicto funciona también recibe este aviso cuando la aplicación no leyó ninguno de los relojes que la sesión sustituye, o cuando es un programa en Go, cuyo reloj de pared Chrono Mock no alcanza. El archivo también nombra la ejecución en sí: la versión, cuándo empezó, el objetivo, su carpeta y las opciones. |
--report-args |
Junto con --report, escribe también los argumentos del objetivo en ese archivo, palabra por palabra. Desactivado por defecto, porque un argumento puede llevar una contraseña - el archivo dice entonces solo cuántos había. |
--json |
Emite la sesión como registros legibles por máquina en lugar del informe - el mismo flujo que consume la propia ventana. La salida propia de una aplicación de consola va a la salida de error estándar, así que la salida estándar contiene los registros y nada más. Una aplicación que sigue en marcha cuando termina la sesión sigue escribiendo ahí, de modo que todo lo que lea la salida de error hasta el final la espera, y la ejecución lo dice. |
chrono run - códigos de salida
El código de salida es el veredicto de la sesión, no lo que devolvió la aplicación. El código de salida propio de la aplicación se informa aparte, en el informe y en los datos de la sesión - la página CLI y CI explica por qué es así.
| Código | Significado |
|---|---|
| 0 | funciona - todo proceso que leyó la hora vio el reloj de la sesión |
| 10 | funciona parcialmente - algunos canales cubiertos, otros no |
| 11 | no funciona - la sustitución no llegó a los canales clave |
| 4 | indeterminado - no se pudo establecer la cobertura. Un «no puedo saberlo» honesto, nunca un éxito fingido |
| 12 | el objetivo desapareció justo después de la inyección sin dejar nada ejecutándose con el reloj de la sesión, lo que sugiere una aplicación de instancia única que cede el control a una copia ya en marcha, o un traspaso a un programa en el que la sesión no pudo entrar, normalmente de la otra arquitectura (32/64 bits). Un objetivo que inicia la aplicación y termina es un lanzador, y la sesión continúa para la aplicación |
| 1 | error de uso - una opción incorrecta, una expresión incorrecta o un escenario que este comando no acepta |
| 2 | el objetivo no se pudo lanzar ni inyectar |
| 3 | error interno - el motor no pudo arrancar, llegó a un estado inesperado o se detuvo antes de cerrar la sesión (sea cual sea su propio código de salida). Una ejecución así no lleva veredicto |
| 5 | la operación no está incluida en esta versión - por ejemplo un escenario cuyo momento necesita un calendario que run todavía no puede cargar. Distinto a propósito de un error de uso: pediste algo que aún no existe, no algo incorrecto |
| 6 | la ejecución se cortó - venció --timeout, o el motor dejó de responder durante 15 segundos y se detuvo. No es un veredicto: la sesión se interrumpió, así que no demuestra nada sobre el objetivo en ningún sentido |
| 7 | ya hay otra sesión en marcha - solo una sesión a la vez. Basta con volver a intentarlo cuando termine |
| 8 | la sesión llegó a un veredicto, pero su evidencia no está en el archivo que indica --report - el disco estaba lleno, u otro programa mantenía abierto el archivo anterior, que entonces queda como estaba. El veredicto sigue en el informe que imprime el comando |
Cómo leer el informe
Sin --json, la sesión termina con un informe en texto plano. Cada línea es o bien un
hecho que la sesión observó, o bien está ausente - nada se rellena con un valor por defecto
verosímil.
Chrono Mock - session report
target: .\build\test.exe
verdict: WORKS - time substitution took effect (processes: 1)
every process that read time saw the session clock
session: fake clock reached 2038-01-19T03:14:08
real elapsed 1.3s, fake elapsed 1.3s
exited: the target closed itself with code 3
covered channels (substituted, with call counts, 10 calls in all):
- pid 21240: GetSystemTimeAsFileTime (5 calls)
- pid 21240: GetLocalTime (5 calls)
observed channels (hooked but left real):
- pid 21240: NtCreateUserProcess (0 calls)
warnings:
- the target opened a network connection ...
- verdict - el veredicto de toda la familia sobre el proceso padre y cada proceso hijo, con el número de procesos. Es el número que lleva el código de salida.
- exited - el código de salida propio de la aplicación, y solo cuando
se cerró ella misma. Una ejecución acotada con
--ticksdeja el objetivo en marcha, una sesión Chromium es una que cierra la propia herramienta, y una sesión que nunca arrancó no tiene ese código - la línea falta entonces en lugar de mostrar un cero inventado. Un código de fallo llega como un número negativo grande, así que también recibe su forma hexadecimal. - covered - los canales a los que llegó la sustitución, con cuántas veces se llamó realmente a cada uno, por proceso. Los recuentos nunca se suman entre procesos: la auditoría de un proceso no debe tomar prestadas las cifras de otro. Un contador se detiene en 1048576 y entonces indica al menos esa cifra.
- observed - canales interceptados pero dejados deliberadamente en real, como las esperas de objetos y los temporizadores multimedia. Su propia categoría, para que nunca se lean como sustituidos.
- uncovered - canales que la aplicación pidió y la sesión no cubrió. Es lo que convierte un veredicto en parcialmente.
- not fully cleaned up - todo lo que la limpieza no pudo retirar. Ausente en un final limpio, que es el caso normal.
chrono calc - opciones
Sin lenguaje natural: cada opción es un paso, y el orden de las opciones es el orden de los pasos. Se imprime el resultado tras cada paso, de modo que un paso erróneo se ve en lugar de quedar enterrado.
| Opción | Qué hace |
|---|---|
--base today|now|<moment> |
Dónde empezar, por defecto today. Se resuelve en la zona de la sesión. Un día
imposible como 2025-02-31 se rechaza, nunca se normaliza en silencio al mes
siguiente. |
--base-utc <moment> |
Como --base, pero el inicio es un instante en UTC, con una
Z final opcional, en lugar de una lectura de reloj de pared en la zona de
la sesión. |
--shift ±N<unit> |
Repetible. El signo es obligatorio. Unidades: s m h d w mo q y bd, o sus
nombres completos. m son minutos, mo son
meses. Los meses, trimestres y años se pliegan sobre la fecha del calendario con un
tope, de modo que un mes después del 31 de enero es el final de febrero, no un número fijo
de ticks. bd (días laborables) necesita --calendar. |
--set-time HH:MM:SS | Fija la hora del día sobre el resultado actual. |
--snap <target> |
Salta a un límite de periodo: som eom soq eoq soy eoy (inicio o fin de mes,
trimestre, año). Un inicio es el primer día a las 00:00:00, un fin el último día a las
23:59:59. |
--nearest nbd|pbd |
El día laborable más cercano hacia delante o hacia atrás, incluido el día actual cuando ya
lo es. Necesita --calendar. |
--to-zone +HH:MM |
Un paso: reexpresa el mismo instante en otro desfase fijo. El instante se
conserva, así que el valor epoch no se mueve y solo cambian los campos civiles. No debe
confundirse con --zone. |
--zone +HH:MM |
La zona de la sesión, usada para resolver today y now y para
mostrar el resultado. Sin ella, la zona del equipo. |
--calendar us-banking|us-federal|pl |
Carga un calendario de festivos. Añade día laborable y festivo a los metadatos y
habilita bd y --nearest. Los dos calendarios estadounidenses
difieren en cómo observan un festivo que cae en fin de semana, que es exactamente el
tipo de desfase de un día que una prueba debe encontrar. Cada calendario responde por
un rango de años: pl desde 2002, us-federal desde 1960 y
us-banking desde 2008. Un paso de días hábiles que llegue a un día
anterior se rechaza con el código 1, y una fecha anterior se muestra como no juzgada.
Cuando los festivos de un calendario se comprobaron con la ley hace más de un año, un
día posterior que juzgó lleva la marca calendar_outdated, porque puede
faltar un festivo más reciente. |
--preset <id> --param id=value |
Un momento con nombre de presets/<id>.json, con sus parámetros
rellenados. Excluyente con las opciones de paso y con --analyze, y se combina
con --calendar, --zone y --format. |
--analyze <date> |
Lee de vuelta una fecha pegada y dice qué es. Un 04/08 ambiguo se muestra en
sus dos lecturas, la estadounidense y la polaca, en lugar de adivinarse -
esa ambigüedad es una fuente real de informes de error equivocados. |
--format <mask> |
Imprime también el resultado con tu propia máscara, para que coincida con el formato de la
aplicación probada: yyyy-MM-dd HH:mm:ss. Los tokens distinguen mayúsculas y
minúsculas al estilo de .NET y Java - M es mes, m es
minuto. |
--json |
Salida para máquinas (chronomock.calc/1) para todo lo anterior, de modo que un
pipeline pueda calcular una fecha y devolverla directamente a
chrono run. |
# Último día laborable del trimestre, calendario bancario estadounidense chrono calc --base today --snap eoq --nearest pbd --calendar us-banking
chrono calc - códigos de salida
Una tabla aparte y más pequeña: la calculadora no tiene un veredicto de cobertura que informar.
| Código | Significado |
|---|---|
| 0 | calculado |
| 1 | error de uso - una opción incorrecta, una fecha imposible, un desbordamiento de rango o un archivo de calendario sin ningún día laborable |
| 5 | el paso o la unidad no está incluido en esta versión, o el paso necesita un calendario que no pasaste. Separado de un error de uso a propósito, para que un script distinga «todavía no» de «incorrecto» |