pkgs/ffigen/test/README.md

# FFIgen testing

## Running Tests

1.  Some tests require that dynamic libraries be built before running the tests.
    You can do so with:

    ```shell
    dart run test/setup.dart
    ```

2.  Run the tests with:

    ```shell
    dart test
    ```

## Development

Some tests verify that the generated Dart FFI bindings match a golden file.

For example, the test
[`test/native_test/native_test.dart`](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/test/native_test/native_test.dart)
works by:

1.  Loading the dynamic library for
    [`test/native_test/native_test.c`](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/test/native_test/native_test.c)
    (which was generated by `dart run test/setup.dart`).

2.  Generating binding files for that dynamic library in the
    `test/.temp test output` directory.

3.  Comparing the golden file (i.e.
    [`test/native_test/_expected_native_test_bindings.dart`](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/test/native_test/_expected_native_test_bindings.dart))
    to the generated file and generating a test failure if they do not match.

4.  Using the *golden* bindings to excercise the dynamic library.

If you modify any source for a dynamic library (e.g. any `.c`, `.h` or `.m`
files), then you should run:

```shell
dart run test/setup.dart  # Rebuild the dynamic libraries.
```

To regenerate the golden file, set the environment variable `UPDATE=true`, then
rerun the test:

```shell
UPDATE=true dart test test/native_test/native_test.dart
```

> Note: you should verify that the changes to the golden bindings are
> reasonable with `git diff`.