Testing Guides (Markdown Edition)

These guides replace the legacy Python scripts that used to live in examples/test_guides/. Instead of running massive ad-hoc scripts, you can now follow these concise workflows.

Example modules such as examples.cli.quickstart and examples.basic.pytorch_demo are available only in a source checkout. Pip users should use the CLI validation flows below.

CPU-Only Sanity Check

Even without a GPU, you can verify the installation, inspect system info, and exercise the CLI.

# Show system + GPU summary (falls back to CPU)
gpumemprof info

# Run the CLI validation (pip users: this works; source users can also run python -m examples.cli.quickstart)
gpumemprof track --duration 2 --interval 0.5 --output track.json --format json
gpumemprof analyze track.json --format txt --output analysis.txt
gpumemprof diagnose --duration 0 --output ./diag

For more CPU-focused tips, see the CPU Compatibility Guide.

CPU Smoke Test (Automated)

Use this duo whenever CUDA isn’t available:

# Step 1: disable CUDA and run the CLI validation
set CUDA_VISIBLE_DEVICES=    # PowerShell/CMD
# or: export CUDA_VISIBLE_DEVICES=   # macOS/Linux shells
gpumemprof info
gpumemprof track --duration 10 --interval 0.5 --output track.json --format json
gpumemprof analyze track.json --format txt --output analysis.txt
gpumemprof diagnose --duration 0 --output ./diag

# Step 2: verify system-info fallbacks (source checkout only)
pytest tests/test_utils.py

On Apple Silicon, clearing CUDA_VISIBLE_DEVICES disables CUDA but gpumemprof info may still report the mps backend. Treat this as a non-CUDA smoke test rather than a strict CPU-only force.

Both steps run quickly and unblock CI jobs that lack GPUs.

PyTorch GPU Checklist

Source checkout only. Pip users should use the CLI commands and Python snippets from the Usage Guide.

# Basic profiling walkthrough
python -m examples.basic.pytorch_demo

# Advanced tracker/watchdog demo
python -m examples.advanced.tracking_demo

Both scripts emit summaries, alert counts, and export artifacts under artifacts/advanced_demo/.

TensorFlow GPU Checklist

Source checkout only. Pip users should use the CLI commands and Python snippets from the Usage Guide.

Start with the workload-backed /GPU:0 matmul recipe in TensorFlow Production Recipes when you are bringing up a GPU runtime. After that succeeds, use the training-backed example below:

python -m examples.basic.tensorflow_demo

The demo configures memory growth automatically and prints peak/average memory statistics gathered via TFMemoryProfiler, but it is a deeper training-backed check than the cookbook bring-up recipe.

CLI Smoke Test (PyTorch + TensorFlow)

Source checkout only. Pip users should use the CLI validation in the CPU-only sanity check above.

python -m examples.cli.quickstart

This runs the same commands exercised in CI (gpumemprof --help, info, optional monitor, and the equivalent tfmemprof commands).

Scenario Modules (Telemetry + OOM + Diagnose)

Source checkout only. Pip users should use the CLI commands and Python snippets from the Usage Guide.

python -m examples.scenarios.cpu_telemetry_scenario
python -m examples.scenarios.mps_telemetry_scenario
python -m examples.scenarios.oom_flight_recorder_scenario --mode simulated
python -m examples.scenarios.tf_end_to_end_scenario

Prefer an interactive dashboard? Launch the Textual TUI:

pip install "stormlog[tui,torch]"
stormlog

Enabling the CUDA Path

Ready to profile on GPUs? Follow the GPU Setup Guide for driver + framework installation instructions (PyTorch CUDA wheels, TensorFlow GPU wheel, and verification commands). Once complete, unset CUDA_VISIBLE_DEVICES (or point it to a real GPU), run the cookbook GPU bring-up recipes, and then rerun the PyTorch/TensorFlow checklists above.

Automation Tips

  • Source checkout users can integrate the demos into release or pre-commit scripts with python -m examples.basic.*.

  • Pip users can automate the CLI validation flows from the CPU-only sanity check instead.

  • Use pytest tests/test_utils.py for a lightweight regression check when GPUs are not available.

  • CI splits built-wheel CLI smoke from source-checkout example smoke; feel free to add extra jobs that execute the PyTorch/TensorFlow demos on GPU-enabled runners.