DEV Community: Yelaman Yelmuratov

Stop Writing Analytics Code. Start Defining It

Yelaman Yelmuratov — Sat, 22 Nov 2025 17:50:10 +0000

Type-safe analytics, automated documentation, and data integrity-from a single source of truth.

As a Developer who has seen the inside of massive codebases, I've witnessed the same tragedy play out in almost every product team.

It starts innocently. A Product Manager asks for a new event: user_clicked_button.
A developer adds analytics.logEvent('user_clicked_button').
A week later, another developer adds analytics.logEvent('UserClickedButton').
A month later, a data analyst asks why the button_id parameter is a string in iOS but an integer in Android.
Six months later, your dashboard is a graveyard of untrustworthy data.

We treat our production code with rigor-CI/CD, type safety, code reviews. Yet we treat our analytics-the very data that drives our business decisions-like a "stringly typed" afterthought.

It's time to stop writing analytics code by hand.

Meet analytics_gen, a tool designed to bring engineering discipline to your data pipeline.

The Philosophy: Schema First

The core problem with analytics is drift. The implementation drifts from the spec, the docs drift from the code, and the platforms drift from each other.

analytics_gen solves this by enforcing a Single Source of Truth. You define your analytics plan in YAML, and the tool generates everything else.

1. Type-Safe Dart Code

Instead of guessing event names and parameter keys, you get a generated, type-safe API.

❌ Before (The "Stringly Typed" Nightmare):

// Hope you spelled 'purchase_completed' right...
// And is 'value' a double or an int?
analytics.logEvent('purchase_completed', {'value': 99.99});

✅ After (The analytics_gen Way):

// Compile-time checked. Autocompleted. Documented.
analytics.logPurchaseCompleted(
  value: 99.99,
  currency: 'USD',
  itemCount: 3,
);

If you change a parameter in the YAML, your build fails until you update the code. No more silent regressions.

2. Validation at the Source

Garbage in, garbage out. If your analytics ingestion pipeline is receiving bad data, your charts are lying to you. analytics_gen lets you define validation rules directly in your schema.

# events/search.yaml
search_event:
  parameters:
    query:
      type: string
      min_length: 3
      regex: "^[a-zA-Z0-9 ]+$"
    category:
      type: string
      allowed_values: ['electronics', 'books', 'clothing']

The generator creates runtime checks that enforce these rules before the event leaves the client. It also generates Dart enums for allowed_values, making invalid states unrepresentable.

3. Automated Documentation & Exports

Your stakeholders (PMs, Data Analysts) don't read Dart code. They need documentation.
analytics_gen automatically generates:

📘 Markdown Docs: Always up-to-date, readable descriptions of every event and parameter.
📊 CSV/JSON Exports: Machine-readable schemas that can be ingested by your data warehouse (BigQuery, Snowflake) to validate incoming data.
🗄️ SQL Schemas: Ready-to-run CREATE TABLE statements.

Built for Scale

I built analytics_gen with the constraints of large-scale engineering in mind.

Domain Splitting: Break your plan into multiple YAML files (e.g., auth.yaml, checkout.yaml) so different teams can own their domains without merge conflict hell.
Shared Parameters: Define user_id or session_id once in shared.yaml and reuse them everywhere. DRY applied to data.
Dual-Write Migration: Changing event names or structures? Use dual_write_to to log to both the old and new events simultaneously during the transition, ensuring zero data loss.

Architecture: Flexible & Robust

The generated code doesn't lock you into a specific provider. It sits above your SDKs.

🔌 Multi-Provider Support: Send the same event to Firebase, Amplitude, and your internal warehouse with a single call.
⚡ Async & Batching: The generated API is synchronous (fire-and-forget) so it never blocks your UI, but the backend supports async buffering, retries, and batching for network efficiency.
🌍 Contexts: Manage global state (like user_role or theme) separately from ephemeral events.

Try It Out

If you're tired of debugging why your funnel drop-off looks wrong, or if you just want the same level of tooling for your data as you have for your app logic, give analytics_gen a try.

It's not just a code generator; it's a contract between your code and your data.

Get started on pub.dev • Star on GitHub

Approval Testing with Widget tests | Flutter / Dart 🎯

Yelaman Yelmuratov — Wed, 03 Jul 2024 07:15:23 +0000

Hi there, I already wrote an article about ApprovalTests for unit tests.
In this article we will touch on Widget tests and how this package can be useful for us.

Let's briefly go through again what exactly are ApprovalTests?

In manual code testing, developers usually write automated tests to guard against regressions, specifying the expected outcomes directly in the code. ApprovalTests uses a similar method but stores the expected outcomes in a file instead. This file is generated by the test library rather than the developer, making the process of writing and maintaining tests more efficient. As a result, developers can spend more time on the functional code rather than the test code.

📋 How it works step by step

The first run of the test automatically creates an approved file if there is no such file.
If the changed results match the approved file perfectly, the test passes.
If there's a difference, a reporter tool will highlight the mismatch and the test fails.
If the test is passed, the received file is deleted automatically. You can change this by changing the deleteReceivedFile value in options. If the test fails, the received file remains for analysis.

Instead of writing:

    testWidgets('home page', (WidgetTester tester) async {
        await tester.pumpWidget(const MyApp());
        await tester.pumpAndSettle();

        expect(find.text('You have pushed the button this many times:'), findsOneWidget);
        expect(find.text('0'), findsOneWidget);
        expect(find.byWidgetPredicate(
            (Widget widget) => widget is Text && widget.data == 'hello' && 
            widget.key == ValueKey('myKey'),
        ), findsOneWidget);
        expect(find.text('Approved Example'), findsOneWidget);
    });

Write this:

    testWidgets('home page', (WidgetTester tester) async {
        await tester.pumpWidget(const MyApp());
        await tester.pumpAndSettle();

        await tester.approvalTest();
    });

To include your project's custom widget types in your test, and to perform post-test checks, add calls to Approved.setUpAll() to your tests' setUpAll calls, like so:

    main() {
        setUpAll(() {
            Approved.setUpAll();
        });
    }

And the result will be something like this:

But if we for example change something and run the text, it will show us the difference, where it differs. There are several types of Reporter in the project, but the standard is CommandLineReporter, which gives the difference on the command line. Other reporters can be found in the project's Github repository.

Approving Results

Approving results just means saving the .approved.txt file with your desired results.

We’ll provide more explanation in due course, but, briefly, here are the most common approaches to do this.

• Via Diff Tool

Most diff tools have the ability to move text from left to right, and save the result.
How to use diff tools is just below, there is a Comparator class for that.

• Via CLI command

You can run the command in a terminal to review your files:

dart run approval_tests:review

After running the command, the files will be analyzed and you will be asked to choose one of the options:

y - Approve the received file.
n - Reject the received file.
view - View the differences between the received and approved files. After selecting v you will be asked which IDE you want to use to view the differences.

The command dart run approval_tests:review has additional options, including listing files, selecting
files to review from this list by index, and more. For its current capabilities, run

dart run approval_tests:review --help

• Via approveResult property

If you want the result to be automatically saved after running the test, you need to use the approveResult property in Options:

void main() {
  test('test JSON object', () {
    final complexObject = {
      'name': 'JsonTest',
      'features': ['Testing', 'JSON'],
      'version': 0.1,
    };

    Approvals.verifyAsJson(
      complexObject,
      options: const Options(
        approveResult: true,
      ),
    );
  });
}

this will result in the following file
example_test.test_JSON_object.approved.txt

{
  "name": "JsonTest",
  "features": [
    "Testing",
    "JSON"
  ],
  "version": 0.1
}

• Via file rename

You can just rename the .received file to .approved.

❓ Which File Artifacts to Exclude from Source Control

You must add any approved files to your source control system. But received files can change with any run and should be ignored. For Git, add this to your .gitignore:

*.received.*

Show some 💙 and star the repo to support the project! 🫰

For any questions, feel free to reach out via Telegram or email at yelaman.yelmuratov@gmail.com.

Approval Testing and why it’s important | Dart 🎯

Yelaman Yelmuratov — Wed, 22 May 2024 13:17:33 +0000

Approval Tests provide an alternative approach to traditional assertions in software testing. They are particularly useful when dealing with complex objects, such as long strings, collections, or objects with many properties. By capturing a snapshot of the output and comparing it with an approved version, Approval Tests simplify the process of verifying that your code behaves as expected. This article will introduce the Dart implementation of Approval Tests and demonstrate its use through an example.

What are Approval Tests?

Approval Tests offer a different way to perform assertions in tests. Traditional assertions compare a result directly to an expected value, like this:
expect(a, equals(b));
In contrast, Approval Tests use a verification approach:
Approvals.verify(a);

Here’s how it works:

If the results match the approved file perfectly, the test passes.
If there’s a difference, a reporter tool highlights the mismatch, and the test fails, providing a visual and textual representation of the changes.

If you are fixing a bug (or adding a feature), this will change the expected behavior. Therefore when you run the test, it will fail.

Why Use Approval Tests?

Approval Tests streamline the feedback loop, saving developers time by only highlighting what has changed rather than requiring them to parse through the entire output. This approach is especially beneficial for complex outputs where traditional assertions can be cumbersome.

Dart Implementation of Approval Tests

To use Approval Tests in your Dart project, add the following to your pubspec.yaml file:

dependencies:
  approval_tests: ^1.0.0

Getting Started

Download and open the starter project: Approvaltests.Dart.StarterProject

This project includes:

A .gitignore file to exclude approval artifacts.
A linter with all rules in place.
A GitHub action to run tests, with the test status visible on the README.md badge.

To use Approval Tests:

Set up a test: Import the Approval Tests library into your code.
Optionally, set up a reporter: Reporters highlight differences between approved and received files when a test fails. The default reporter is the CommandLineReporter. You can also use the DiffReporter to compare files in your IDE. The package currently supports VS Code and Android Studio. If by some errors or other reason you want to make your own, there is a customDiffInfo option.
Manage the “approved” file: When the test is run for the first time, an approved file is created automatically. This file represents the expected outcome. Once the test results are satisfactory, update the approved file to reflect these changes.

Approving Results

Approving results involves saving the .approved.txt file with your desired results. Common approaches include:

Using a diff tool to move text from left to right and save the result.
Using the approveResult property in Options for automatic approval after running the test.
Renaming the .received file to .approved.

Reporters

Reporters launch diff tools when things do not match, making it easy to see changes. Available reporters include:

CommandLineReporter: Outputs the diff in the terminal.

DiffReporter: Opens the Diff Tool in your IDE.

Example: Gilded Rose Kata

The following example demonstrates how to use Approval Tests to refactor the GildedRose non-refactored code from the Gilded Rose Kata:

final class GildedRose {
  final List<Item> items;

  GildedRose({required this.items});

  void updateQuality() {
    for (int i = 0; i < items.length; i++) {
      if (items[i].name != "Aged Brie" &&
          items[i].name != "Backstage passes to a TAFKAL80ETC concert") {
        if (items[i].quality > 0) {
          if (items[i].name != "Sulfuras, Hand of Ragnaros") {
            items[i].quality = items[i].quality - 1;
          }
        }
      } else {
        if (items[i].quality < 50) {
          items[i].quality = items[i].quality + 1;
          if (items[i].name == "Backstage passes to a TAFKAL80ETC concert") {
            if (items[i].sellIn < 11) {
              if (items[i].quality < 50) {
                items[i].quality = items[i].quality + 1;
              }
            }
            if (items[i].sellIn < 6) {
              if (items[i].quality < 50) {
                items[i].quality = items[i].quality + 1;
              }
            }
          }
        }
      }
      if (items[i].name != "Sulfuras, Hand of Ragnaros") {
        items[i].sellIn = items[i].sellIn - 1;
      }
      if (items[i].sellIn < 0) {
        if (items[i].name != "Aged Brie") {
          if (items[i].name != "Backstage passes to a TAFKAL80ETC concert") {
            if (items[i].quality > 0) {
              if (items[i].name != "Sulfuras, Hand of Ragnaros") {
                items[i].quality = items[i].quality - 1;
              }
            }
          } else {
            items[i].quality = items[i].quality - items[i].quality;
          }
        } else {
          if (items[i].quality < 50) {
            items[i].quality = items[i].quality + 1;
          }
        }
      }
    }
  }
}

final class Item {
  final String name;
  int sellIn;
  int quality;

  Item(this.name, {required this.sellIn, required this.quality});

  @override
  String toString() => 'Item{name: $name, sellIn: $sellIn, quality: $quality}';
}

Test code:

import 'package:approval_tests/approval_tests.dart';
import 'package:starter_project/starter_project.dart';
import 'package:test/test.dart';

void main() {
  // Define all test cases
  const allTestCases = [
    [
      "foo",
      "Aged Brie",
      "Backstage passes to a TAFKAL80ETC concert",
      "Sulfuras, Hand of Ragnaros",
    ],
    [-1, 0, 5, 6, 10, 11],
    [-1, 0, 1, 49, 50],
  ];

  group('Approval Tests for Gilded Rose', () {
    test('verify all combinations', () {
      Approvals.verifyAllCombinations(
        allTestCases,
        // options: const Options(
        //   reporter: DiffReporter(),
        // ),
        processor: processItemCombination,
      );
    });
  });
}

// Function to process each combination and generate output for verification
String processItemCombination(Iterable<List<dynamic>> combinations) {
  final receivedBuffer = StringBuffer();

  for (final combination in combinations) {
    // Extract data from the current combination
    final String itemName = combination[0] as String;
    final int sellIn = combination[1] as int;
    final int quality = combination[2] as int;

    // Create an Item object representing the current combination
    final Item testItem = Item(itemName, sellIn: sellIn, quality: quality);

    // Passing testItem to the application
    final GildedRose app = GildedRose(items: [testItem]);

    // Updating quality of testItem
    app.updateQuality();

    // Adding the updated item to expectedItems
    receivedBuffer.writeln(testItem.toString());
  }

  // Return a string representation of the updated item
  return receivedBuffer.toString();
}

And at the output we get 120 different combinations based on which we can start refactoring our code. Of course, you can divide the combination generation into parts and remove unnecessary combinations, but this is just an example.

Conclusion

Approval Tests for Dart offer a powerful alternative to traditional assertions, particularly for complex objects and outputs. By simplifying the verification process, they help developers focus on what has changed, reducing the time and effort needed to understand the impact of their code changes. For more information, examples, and how to contribute, visit the Approval Tests Dart repository.

Please note, this is my first article and my initial public library. I’m actively communicating with Approval Tests creator Llewelyn Falco about improvements to the library. Your suggestions, issues, and pull requests are highly encouraged and welcomed. Let’s make this library even better together! 🙌

Show some 💙 and star the repo to support the project! 🫰

For any questions, feel free to reach out via Telegram or email at yelaman.yelmuratov@gmail.com.