Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,9 @@ Do not pipe pytest through `| tail -N` if you want streaming output; it buffers
- Test command: `bash test` or targeted subsets above.
- Prefer native Rust implementations and fail-loud behavior over silent Python fallbacks.
- Do not add backwards-compat hacks for code paths that no longer exist.
- For deterministic in-product render checks, use `fastled <sketch> --test`
with the `--test-*` screenshot, interval, log, and timeout flags. This uses
the shipped Tauri viewer and exits automatically; no browser harness is needed.

## Common Gotchas

Expand Down
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,28 @@ Useful flags:

Set `FASTLED_VIEWER_LOGS=1` to forward the viewer window's browser console output (`console.*`, uncaught errors, failed fetches) to the terminal's stderr, prefixed with `[viewer]` — useful when diagnosing a blank or broken viewer.

### Testing your sketch from CI or an agent

The shipped viewer can render a sketch, capture its canvas, collect browser
logs, and exit without Playwright or a separate browser installation:

```bash
fastled examples/Blink --test --test-wait-secs=2 \
--test-screenshot=out/blink.png --test-log=out/blink.viewer.log \
--test-exit-on-error
```

For a frame sequence, add
`--test-interval-secs=0.5 --test-count=10` and use a path such as
`out/blink-{n:03}.png`. The interval is the target between scheduled capture
starts; slow canvas readback or uploads can delay later frames. The wait begins
only after the compiled page has a canvas and two animation frames have
elapsed. Exit codes are `0` for success,
`1` for compile/viewer/I/O failure, `2` for a captured page error when
`--test-exit-on-error` is enabled, `124` for the total timeout, and `125` for
the ready timeout. An interrupted run exits `130`. The viewer and local server
are stopped automatically.

## Features

### Browser Compatibility
Expand Down
1 change: 1 addition & 0 deletions crates/fastled-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ tempfile = "3"
zccache-fingerprint = { workspace = true }
shell-words = { workspace = true }
globset = { workspace = true }
getrandom = "0.3"

[build-dependencies]
indexmap = { version = "1.9.3", features = ["std"] }
Expand Down
148 changes: 148 additions & 0 deletions crates/fastled-cli/src/cli.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
use std::path::PathBuf;

use clap::{Parser, Subcommand, ValueEnum};

#[derive(Clone, Debug, Subcommand)]
Expand Down Expand Up @@ -111,6 +113,82 @@ pub(crate) struct Cli {
#[arg(long)]
pub(crate) no_https: bool,

/// Compile, render, collect requested test artifacts, and exit.
#[arg(long, conflicts_with_all = ["just_compile", "no_app"], help_heading = "Production testing")]
pub(crate) test: bool,

/// Seconds to wait after the sketch is ready before the first capture.
#[arg(
long,
default_value_t = 1.0,
requires = "test",
help_heading = "Production testing"
)]
pub(crate) test_wait_secs: f64,

/// PNG output path. Interval mode supports an unpadded index, {n:03}, and {ts}.
#[arg(
long,
value_name = "PATH",
requires = "test",
verbatim_doc_comment,
help_heading = "Production testing"
)]
pub(crate) test_screenshot: Option<PathBuf>,

/// Target interval between scheduled capture starts; slow captures may delay later frames.
#[arg(long, requires = "test", help_heading = "Production testing")]
pub(crate) test_interval_secs: Option<f64>,

/// Number of screenshots to take in interval mode.
#[arg(
long,
requires = "test",
conflicts_with = "test_duration_secs",
help_heading = "Production testing"
)]
pub(crate) test_count: Option<u32>,

/// Total capture window in seconds for interval mode.
#[arg(
long,
requires = "test",
conflicts_with = "test_count",
help_heading = "Production testing"
)]
pub(crate) test_duration_secs: Option<f64>,

/// Append viewer console and error output to this file.
#[arg(
long,
value_name = "PATH",
requires = "test",
help_heading = "Production testing"
)]
pub(crate) test_log: Option<PathBuf>,

/// Exit with code 2 when the viewer reports a page-side error.
#[arg(long, requires = "test", help_heading = "Production testing")]
pub(crate) test_exit_on_error: bool,

/// Hard upper bound in seconds for compile, ready wait, and capture.
#[arg(
long,
default_value_t = 120.0,
requires = "test",
help_heading = "Production testing"
)]
pub(crate) test_timeout_secs: f64,

/// Seconds to wait for a rendered canvas after compilation succeeds.
#[arg(
long,
default_value_t = 15.0,
requires = "test",
help_heading = "Production testing"
)]
pub(crate) test_ready_timeout_secs: f64,

/// Use the latest tagged FastLED release when initialising examples with --init.
/// Defaults to `master`; tagged releases older than the meson migration cannot be built.
#[arg(long)]
Expand Down Expand Up @@ -181,6 +259,12 @@ pub(crate) fn validate_init_ref_flags(cli: &Cli) -> Result<(), &'static str> {
Ok(())
}

pub(crate) fn apply_test_implications(cli: &mut Cli) {
if cli.test {
cli.no_interactive = true;
}
}

pub(crate) fn requested_init_ref(cli: &Cli) -> Option<&str> {
if cli.latest {
// `--latest` opts into the most recent tagged FastLED release. The
Expand All @@ -202,6 +286,7 @@ pub(crate) fn requested_init_ref(cli: &Cli) -> Option<&str> {
#[cfg(test)]
mod tests {
use super::*;
use clap::CommandFactory;

#[test]
fn clangd_emission_is_opt_in() {
Expand Down Expand Up @@ -235,4 +320,67 @@ mod tests {
})
));
}

#[test]
fn production_test_flags_parse_as_a_group() {
let cli = Cli::parse_from([
"fastled",
"sketch",
"--test",
"--test-wait-secs=2",
"--test-interval-secs=0.5",
"--test-count=10",
"--test-screenshot=out-{n:03}.png",
"--test-log=run.log",
"--test-exit-on-error",
]);
assert!(cli.test);
assert_eq!(cli.test_wait_secs, 2.0);
assert_eq!(cli.test_interval_secs, Some(0.5));
assert_eq!(cli.test_count, Some(10));
assert_eq!(cli.test_screenshot, Some(PathBuf::from("out-{n:03}.png")));
assert_eq!(cli.test_log, Some(PathBuf::from("run.log")));
assert!(cli.test_exit_on_error);
}

#[test]
fn production_test_help_describes_filename_templates() {
let help = Cli::command().render_long_help().to_string();
assert!(help.contains("supports an unpadded index, {n:03}, and {ts}"));
assert!(help.contains("Target interval between scheduled capture starts"));
}

#[test]
fn test_mode_implies_non_interactive_before_directory_resolution() {
let mut cli = Cli::parse_from(["fastled", "--test"]);
assert!(!cli.no_interactive);
apply_test_implications(&mut cli);
assert!(cli.no_interactive);
}

#[test]
fn production_test_suboptions_require_master_switch() {
assert!(Cli::try_parse_from([
"fastled",
"sketch",
"--test-count=2",
"--test-interval-secs=.5",
"--test-screenshot=out-{n}.png"
])
.is_err());
}

#[test]
fn production_test_count_and_duration_conflict() {
assert!(Cli::try_parse_from([
"fastled",
"sketch",
"--test",
"--test-count=2",
"--test-duration-secs=1",
"--test-interval-secs=.5",
"--test-screenshot=out-{n}.png"
])
.is_err());
}
}
Loading
Loading