From e49b9fbf66c5d97bdccc72de0bdab854799ecc75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Gro=C3=9F?= Date: Wed, 14 Jan 2026 20:05:44 +0100 Subject: [PATCH 1/7] . --- README.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 84d1008f..e51ce0ba 100644 --- a/README.md +++ b/README.md @@ -17,4 +17,34 @@ There are four related projects that make use of MathCAT: MathCAT is used in many assistive technologies including NVDA and JAWS. -For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). \ No newline at end of file +For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). + +## Test Coverage + +This section explains test coverage with `llvm-cov` and `grcov` on _MacOS_. + +Using other operating systems should also work with [grcov](https://github.com/mozilla/grcov), but may require some tweaks +regarding LLVM, paths, etc. + +```bash +# One-time setup +rustup component add llvm-tools-preview +cargo install grcov + +export LLVM_PROFILE_FILE="target/coverage/%p-%m.profraw" +RUSTFLAGS="-Cinstrument-coverage" cargo test +# Example with a single test: +# RUSTFLAGS="-Cinstrument-coverage" cargo test Languages::zh::tw::units::without_prefix_powers_of_2 + +# Generate report +grcov . \ + --source-dir . \ + --binary-path ./target/debug/deps \ + -t html \ + --branch \ + --ignore-not-existing \ + --ignore "target/*" \ + -o target/coverage/html + +open target/coverage/html/index.html +``` From 5ea9da6b6cafd00928f258565cc27335096452b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Gro=C3=9F?= Date: Wed, 14 Jan 2026 20:15:23 +0100 Subject: [PATCH 2/7] . --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e51ce0ba..500ea24c 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ There are four related projects that make use of MathCAT: MathCAT is used in many assistive technologies including NVDA and JAWS. -For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). +- For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). ## Test Coverage From e446fdf6eeb7f87bb17559d607a4b77a28c36777 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Gro=C3=9F?= Date: Wed, 14 Jan 2026 20:16:12 +0100 Subject: [PATCH 3/7] Revert "." This reverts commit 5ea9da6b6cafd00928f258565cc27335096452b6. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 500ea24c..e51ce0ba 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ There are four related projects that make use of MathCAT: MathCAT is used in many assistive technologies including NVDA and JAWS. -- For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). +For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). ## Test Coverage From e694775d89fd9af81eec23bccbe5ad5d137e09b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Gro=C3=9F?= Date: Wed, 14 Jan 2026 20:16:57 +0100 Subject: [PATCH 4/7] . --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e51ce0ba..c656c485 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,8 @@ For more information, see the [full documentation](https://nsoiffer.github.io/Ma This section explains test coverage with `llvm-cov` and `grcov` on _MacOS_. -Using other operating systems should also work with [grcov](https://github.com/mozilla/grcov), but may require some tweaks -regarding LLVM, paths, etc. +Using other operating systems should also work with [grcov](https://github.com/mozilla/grcov), +but may require some tweaks regarding LLVM, paths, etc. ```bash # One-time setup From 2210d852623d2fe1a7713d30a1ec3a0e3463bc94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Gro=C3=9F?= Date: Thu, 15 Jan 2026 19:01:39 +0100 Subject: [PATCH 5/7] move test-coverage explainer to helpers.md --- README.md | 30 ------------------------------ docs/helpers.md | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index c656c485..d9c3219a 100644 --- a/README.md +++ b/README.md @@ -18,33 +18,3 @@ There are four related projects that make use of MathCAT: MathCAT is used in many assistive technologies including NVDA and JAWS. For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). - -## Test Coverage - -This section explains test coverage with `llvm-cov` and `grcov` on _MacOS_. - -Using other operating systems should also work with [grcov](https://github.com/mozilla/grcov), -but may require some tweaks regarding LLVM, paths, etc. - -```bash -# One-time setup -rustup component add llvm-tools-preview -cargo install grcov - -export LLVM_PROFILE_FILE="target/coverage/%p-%m.profraw" -RUSTFLAGS="-Cinstrument-coverage" cargo test -# Example with a single test: -# RUSTFLAGS="-Cinstrument-coverage" cargo test Languages::zh::tw::units::without_prefix_powers_of_2 - -# Generate report -grcov . \ - --source-dir . \ - --binary-path ./target/debug/deps \ - -t html \ - --branch \ - --ignore-not-existing \ - --ignore "target/*" \ - -o target/coverage/html - -open target/coverage/html/index.html -``` diff --git a/docs/helpers.md b/docs/helpers.md index f10f4e47..d050c7b2 100644 --- a/docs/helpers.md +++ b/docs/helpers.md @@ -252,6 +252,39 @@ Whether you are developing code or writing rules, writing and running the tests The `tests` directory is similar to the `Rules` directory. If you are a translator, see the section above that describes what you should do. +Rust provides testing support with the command `cargo test`. + +### Test Coverage + +This section explains test coverage with `llvm-cov` and `grcov` on _MacOS_. +Another option is using built-in coverage-support of your IDE, for example _RustRover_ by _JetBrains_. + +Using other operating systems should also work with [grcov](https://github.com/mozilla/grcov), +but may require some tweaks regarding LLVM, paths, etc. + +```bash +# One-time setup +rustup component add llvm-tools-preview +cargo install grcov + +export LLVM_PROFILE_FILE="target/coverage/%p-%m.profraw" +RUSTFLAGS="-Cinstrument-coverage" cargo test +# Example with a single test: +# RUSTFLAGS="-Cinstrument-coverage" cargo test Languages::zh::tw::units::without_prefix_powers_of_2 + +# Generate report +grcov . \ + --source-dir . \ + --binary-path ./target/debug/deps \ + -t html \ + --branch \ + --ignore-not-existing \ + --ignore "target/*" \ + -o target/coverage/html + +open target/coverage/html/index.html +``` + ## Files MathCAT reads the following files for critical information: From 36953dd3a772d4ba621dde83fbed5b893ee7f809 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Gro=C3=9F?= Date: Thu, 15 Jan 2026 19:02:53 +0100 Subject: [PATCH 6/7] remove trailing line --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d9c3219a..84d1008f 100644 --- a/README.md +++ b/README.md @@ -17,4 +17,4 @@ There are four related projects that make use of MathCAT: MathCAT is used in many assistive technologies including NVDA and JAWS. -For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). +For more information, see the [full documentation](https://nsoiffer.github.io/MathCAT/). \ No newline at end of file From 6aac09dfdfa0fd443b0b25d06ae84eaa585b9826 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Gro=C3=9F?= Date: Sat, 17 Jan 2026 01:39:35 +0100 Subject: [PATCH 7/7] Add Developer Guide for testing, coverage, and workflow references - Consolidated test coverage details into a new `developers.md`. - Updated `index.md` and `helpers.md` to reference the new guide. --- docs/developers.md | 124 +++++++++++++++++++++++++++++++++++++++++++++ docs/helpers.md | 33 +----------- docs/index.md | 2 +- 3 files changed, 126 insertions(+), 33 deletions(-) create mode 100644 docs/developers.md diff --git a/docs/developers.md b/docs/developers.md new file mode 100644 index 00000000..2bc2f71e --- /dev/null +++ b/docs/developers.md @@ -0,0 +1,124 @@ +# Developer Guide + +This guide provides technical information for developers working on the MathCAT codebase. + +## Prerequisites + +To develop MathCAT, you need to have Rust installed. If you haven't already: + +1. [Download and install Rust](https://www.rust-lang.org/tools/install) +2. Clone the MathCAT repository +3. Open the project directory in your IDE + +## Working with Cargo + +Cargo is Rust's build system and package manager. Here are the essential commands you'll use: + +### Building the Project + +```bash +# Build the project in debug mode +cargo build + +# Build the project in release mode (optimized) +cargo build --release +``` + +### Running the Project + +```bash +# Run the main executable +cargo run + +# Run with specific arguments +cargo run -- +``` + +### Managing Dependencies + +Dependencies are defined in `Cargo.toml`. Cargo automatically downloads and manages them. + +```bash +# Update dependencies to their latest compatible versions +cargo update +``` + +## Testing + +Testing is crucial for maintaining code quality and ensuring that changes don't break existing functionality. + +### Running Tests + +```bash +# Run all tests +cargo test + +# Run a specific test +cargo test test_name +``` + +### Writing Tests + +Tests in MathCAT verify that MathML expressions produce the expected speech output. Example: + +```rust +#[test] +fn test_simple_fraction() { + let expr = " + + 1 + 2 + + "; + test("en", "SimpleSpeak", expr, "1 half"); +} +``` + +### Test Coverage + +Test coverage helps identify which parts of the code are exercised by tests and which parts need more testing. + +
+Using grcov on macOS + +This approach uses `llvm-cov` and `grcov` to generate test coverage reports. Other operating systems should also work with [grcov](https://github.com/mozilla/grcov), but may require some adjustments regarding LLVM paths and configuration. + +**One-time setup:** + +```bash +# Install required components +rustup component add llvm-tools-preview +cargo install grcov +``` + +**Generate coverage report:** + +```bash +# Set environment variable for profiling data +export LLVM_PROFILE_FILE="target/coverage/%p-%m.profraw" + +# Run tests with coverage instrumentation +RUSTFLAGS="-Cinstrument-coverage" cargo test + +# Example: Run a single test +# RUSTFLAGS="-Cinstrument-coverage" cargo test Languages::zh::tw::units::without_prefix_powers_of_2 + +# Generate HTML report +grcov . \ + --source-dir . \ + --binary-path ./target/debug/deps \ + -t html \ + --branch \ + --ignore-not-existing \ + --ignore "target/*" \ + -o target/coverage/html + +# Open the report in your browser +open target/coverage/html/index.html +``` + +
+ +**Alternative: IDE Integration** + +Many Rust IDEs provide built-in test coverage support, like RustRover or VSCode. \ No newline at end of file diff --git a/docs/helpers.md b/docs/helpers.md index d050c7b2..1d2e2d17 100644 --- a/docs/helpers.md +++ b/docs/helpers.md @@ -252,38 +252,7 @@ Whether you are developing code or writing rules, writing and running the tests The `tests` directory is similar to the `Rules` directory. If you are a translator, see the section above that describes what you should do. -Rust provides testing support with the command `cargo test`. - -### Test Coverage - -This section explains test coverage with `llvm-cov` and `grcov` on _MacOS_. -Another option is using built-in coverage-support of your IDE, for example _RustRover_ by _JetBrains_. - -Using other operating systems should also work with [grcov](https://github.com/mozilla/grcov), -but may require some tweaks regarding LLVM, paths, etc. - -```bash -# One-time setup -rustup component add llvm-tools-preview -cargo install grcov - -export LLVM_PROFILE_FILE="target/coverage/%p-%m.profraw" -RUSTFLAGS="-Cinstrument-coverage" cargo test -# Example with a single test: -# RUSTFLAGS="-Cinstrument-coverage" cargo test Languages::zh::tw::units::without_prefix_powers_of_2 - -# Generate report -grcov . \ - --source-dir . \ - --binary-path ./target/debug/deps \ - -t html \ - --branch \ - --ignore-not-existing \ - --ignore "target/*" \ - -o target/coverage/html - -open target/coverage/html/index.html -``` +Rust provides testing support with the command `cargo test`. For more information about testing and test coverage, see the [Developer Guide](developers.md). ## Files diff --git a/docs/index.md b/docs/index.md index 4b969bd0..8c09fff6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,7 +17,7 @@ There are many different audiences for MathCAT and each audience has different i * AT users: [information about preferences you can set](users.md) * AT developers/library users: [information about the API that MathCAT exposes](callers.md) * Translators/Rule writers: [information about the files that need to be translated](helpers.md) -* MathCAT developers: information about MathCAT's design +* MathCAT developers: [information about development workflow and testing](developers.md) # Some Technical Details MathCAT is written in Rust and can be built to interface with many languages. To date there are interfaces for: