Skip to content
Closed
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
17 changes: 17 additions & 0 deletions .cargo/mutants-media-controls.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Windows media-controls pass. Only the pure event-to-command mapping is in
# scope; constructing or pumping native SMTC controls needs a Windows desktop.
examine_globs = ["src/ui/media_controls.rs"]
exclude_globs = ["packaging/**", "src/tests/**", "tests/**", "target/**"]
exclude_re = [
"sync_metadata",
"sync_playback",
"try_new",
"Server::create",
"Server::handle",
"Drop for Server",
"windows::",
]
additional_cargo_args = ["--locked"]
test_tool = "nextest"
minimum_test_timeout = 20
timeout_multiplier = 5
13 changes: 13 additions & 0 deletions .cargo/mutants-mpris.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Linux MPRIS pass. This enables MPRIS and tests the in-process interface,
# command forwarding, and error conversion without requiring a D-Bus session.
examine_globs = ["src/ui/mpris.rs"]
exclude_globs = ["packaging/**", "src/tests/**", "tests/**", "target/**"]
# Server creates a real D-Bus service and publishes native properties. Those
# event-loop and bus interactions need live integration validation. Native CI
# builds the adapter and tests in-process behavior; it does not exercise a bus.
# The Player and Sender remain in scope.
exclude_re = ["Server::"]
additional_cargo_args = ["--locked"]
test_tool = "nextest"
minimum_test_timeout = 20
timeout_multiplier = 5
22 changes: 22 additions & 0 deletions .cargo/mutants.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Keep the default pass on deterministic, frontend-neutral behavior. Native
# adapters have dedicated configurations because their compiled feature sets
# and test boundaries differ by platform.
examine_globs = [
"src/history.rs",
"src/player.rs",
"src/config.rs",
"src/ui/input.rs",
]
exclude_globs = [
"packaging/**",
"src/tests/**",
"tests/**",
"target/**",
]
# EventStream owns a terminal event loop and cannot be exercised without a
# terminal. `message_for` below it remains in scope.
exclude_re = ["listen", "Player::close", "Player::init", "Player::run"]
additional_cargo_args = ["--locked"]
test_tool = "nextest"
minimum_test_timeout = 20
timeout_multiplier = 5
69 changes: 69 additions & 0 deletions .github/workflows/mutation.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
name: Mutation tests

on:
workflow_dispatch:
workflow_call:

jobs:
mutants:
name: ${{ matrix.name }}
runs-on: ${{ matrix.os }}
timeout-minutes: 45
strategy:
fail-fast: false
matrix:
include:
- name: Linux core
os: ubuntu-latest
features: default
config: .cargo/mutants.toml
install_alsa: true
- name: Linux MPRIS adapter
os: ubuntu-latest
features: mpris
config: .cargo/mutants-mpris.toml
install_alsa: true
- name: Windows core
os: windows-latest
features: default
config: .cargo/mutants.toml
install_alsa: false
- name: Windows media controls adapter
os: windows-latest
features: media-controls
config: .cargo/mutants-media-controls.toml
install_alsa: false
- name: macOS configuration and input
os: macos-latest
features: default
config: .cargo/mutants.toml
install_alsa: false
steps:
- uses: actions/checkout@v5
- name: Install ALSA development headers
if: matrix.install_alsa
run: sudo apt-get update && sudo apt-get install -y libasound2-dev
- name: Set up Rust
uses: actions-rust-lang/setup-rust-toolchain@v1
- name: Install mutation test tools
uses: taiki-e/install-action@v2
with:
tool: cargo-mutants@27.1.0 cargo-nextest@0.9.140
- name: Write mutation inventory
if: always()
run: >-
cargo mutants --config ${{ matrix.config }} --list --no-times
--features ${{ matrix.features }} > mutants-inventory.txt
- name: Run mutation tests
run: >-
cargo mutants --config ${{ matrix.config }} --no-shuffle
--features ${{ matrix.features }} --output mutants.out
- name: Upload mutation report
if: always()
uses: actions/upload-artifact@v4
with:
name: mutants-${{ matrix.name }}
path: |
mutants-inventory.txt
mutants.out
if-no-files-found: warn
90 changes: 90 additions & 0 deletions .github/workflows/tooling.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
name: Test tooling

on:
workflow_dispatch:
inputs:
run_mutations:
description: Run the manual native mutation suite
required: false
default: false
type: boolean
push:
branches: ['**']
pull_request:
branches: ['**']

jobs:
linux:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Install ALSA development headers
run: sudo apt-get update && sudo apt-get install -y libasound2-dev
- name: Set up Rust
uses: actions-rust-lang/setup-rust-toolchain@v1
- name: Install test tools
uses: taiki-e/install-action@v2
with:
tool: cargo-nextest@0.9.140 cargo-feature-combinations@0.7.0
- name: Check formatting
run: cargo fmt --check
- name: Run standard tests
run: cargo test --locked
- name: Run default tests with nextest
run: cargo nextest run --locked
- name: Run no-default-features tests with nextest
run: cargo nextest run --locked --no-default-features
- name: Run maximal Linux feature tests with nextest
run: cargo nextest run --locked --features mpris,scrape,extra-audio-formats
- name: Run maximal Linux no-default-features tests with nextest
run: cargo nextest run --locked --no-default-features --features mpris,scrape,extra-audio-formats
- name: Check curated Linux feature combinations
run: cargo fc check --locked --all-targets

windows:
runs-on: windows-latest
steps:
- uses: actions/checkout@v5
- name: Set up Rust
uses: actions-rust-lang/setup-rust-toolchain@v1
- name: Install test tools
uses: taiki-e/install-action@v2
with:
tool: cargo-nextest@0.9.140 cargo-feature-combinations@0.7.0
- name: Run default tests with nextest
run: cargo nextest run --locked
- name: Run no-default-features tests with nextest
run: cargo nextest run --locked --no-default-features
- name: Run maximal Windows feature tests with nextest
run: cargo nextest run --locked --features media-controls,scrape,extra-audio-formats
- name: Run maximal Windows no-default-features tests with nextest
run: cargo nextest run --locked --no-default-features --features media-controls,scrape,extra-audio-formats
- name: Check curated Windows feature combinations
run: cargo fc check --locked --all-targets

macos:
runs-on: macos-latest
steps:
- uses: actions/checkout@v5
- name: Set up Rust
uses: actions-rust-lang/setup-rust-toolchain@v1
- name: Install test tools
uses: taiki-e/install-action@v2
with:
tool: cargo-nextest@0.9.140 cargo-feature-combinations@0.7.0
- name: Run default tests with nextest
run: cargo nextest run --locked
- name: Run no-default-features tests with nextest
run: cargo nextest run --locked --no-default-features
- name: Run maximal macOS feature tests with nextest
run: cargo nextest run --locked --features scrape,extra-audio-formats
- name: Run maximal macOS no-default-features tests with nextest
run: cargo nextest run --locked --no-default-features --features scrape,extra-audio-formats
- name: Check curated macOS feature combinations
run: cargo fc check --locked --all-targets

# Each mutation rebuilds/tests changed code. Keep this deeper investigation
# opt-in so normal PR feedback stays bounded; reports still expose failures.
mutation:
if: github.event_name == 'workflow_dispatch' && inputs.run_mutations
uses: ./.github/workflows/mutation.yml
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
/target
/cache
.DS_Store
.DS_Store
mutants*.out
68 changes: 68 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,71 @@ detracts from it's purpose.
More complex features, like fancy colors or cover art, will not be accepted ever. Implementations of
acceptable features should also be simple and not too obtrusive. Even if a feature is simple,
if it is very complex to implement, then it won't be accepted.

## Testing

Install the pinned local tools:

```sh
cargo install --locked cargo-nextest --version 0.9.140
cargo install --locked cargo-feature-combinations --version 0.7.0
cargo install --locked cargo-mutants --version 27.1.0
```

These versions match CI. `--version` selects the tool release; `--locked` uses
that release's packaged dependency lockfile. New releases are not installed
automatically. See the [Cargo installation reference](https://doc.rust-lang.org/cargo/commands/cargo-install.html#dealing-with-the-lockfile).

To evaluate a newer release locally, replace its `--version` value above and
keep `--locked`. Review the release notes and required Rust version; test tools
may require a newer compiler than Lowfi itself. When adopting the release,
update the version here and wherever that tool is installed in
`.github/workflows/tooling.yml` and `.github/workflows/mutation.yml` together.
Verify default/no-default Nextest runs, curated feature checks, and mutation
inventories on the affected native platforms. Run targeted mutation passes if
the upgrade changes mutation behavior. Commit the version updates and validation
results together so contributors and CI use the same tested baseline.

Run `cargo fmt --check`, `cargo test --locked`, `cargo nextest run --locked`,
`cargo nextest run --locked --no-default-features`, and
`cargo fc check --locked --all-targets`. Linux needs ALSA development headers
(`libasound2-dev` on Ubuntu). The curated matrix includes only native platform
features: MPRIS on Linux and media controls on Windows. macOS uses the common
scraping and extra-audio features.

The checked-in four-second MP3 and bounded localhost fixture make download and
decode tests independent of internet services and audio devices. Its generation
command and decoder tolerance are documented beside the fixture.

Mutation inventories and passes are explicit:

```sh
cargo mutants --list
cargo mutants
# Linux only
cargo mutants --config .cargo/mutants-mpris.toml --features mpris --list
cargo mutants --config .cargo/mutants-mpris.toml --features mpris
# Windows only
cargo mutants --config .cargo/mutants-media-controls.toml --features media-controls --list
cargo mutants --config .cargo/mutants-media-controls.toml --features media-controls
```

The default mutation scope covers configuration and terminal input mapping.
The terminal event loop is excluded with `mutants::skip`. The Linux scope covers
in-process MPRIS Player and Sender behavior; Server construction, D-Bus traffic,
and native property publication are excluded. The Windows scope covers event
mapping; native control construction, publication, teardown, and message pumping
are excluded. `sync_metadata` uses `mutants::skip` because struct-field mutants
cannot be excluded reliably by function-name regex. Packaging, fixtures, and
tests are outside mutation scopes.

Treat surviving mutants as test gaps unless these boundaries explain them.
Inspect `mutants.out/missed.txt`, `timeout.txt`, `unviable.txt`, and
`outcomes.json`; timeouts and execution errors require investigation. Use
`cargo mutants --test-tool cargo` only when nextest is unavailable, and never
retry a failed nextest run automatically with another runner.

History mutation coverage includes the bounded model and player transitions.
Player initialization, persistence, and the native command loop are excluded;
dispatch tests use an in-memory terminal handle, and waiter tests render audio
without a device. MPRIS adapter tests need no session bus.
Loading