Projects

This repository holds the source code of the following projects:

• Metrics
• API Mock Server
• Guardian
• Shell Words
• YAML Map

Let's review each of them in a bit more details:

📊 Metrics

Metrics is a set of software components to collect and review software project metrics like performance, build stability, and codebase quality.

The Metrics project integrates with the following CI tools to collect software project metrics:

• Buildkite
• Github Actions
• Jenkins

The Metrics Web Application displays the next project metrics on the dashboard:

Metric	Description
Build Status	A graph indicator displaying the result of the latest build in front of the project's name.
Build Results	A bar chart displaying the build results and duration of the last 30 builds.
Performance	A sparkline graph displaying an average build duration of successful builds by the last 7 days, excluding the queue time.
Builds	A scorecard displaying a count of performed builds of the project per week.
Stability	A circular graph displaying a ratio of successful builds to finished builds for the last 30 builds.
Coverage	A circular graph displaying a last successful build's code coverage percent.

See Project metrics definitions document to get more information about project metrics.

🧪 Api Mock Server

Api Mock Server is a package that provides an abstraction to create mock HTTP servers for testing 3-rd party API integrations. Consider the Third Party API Testing and Mock Server documents for more details.

Features

The API Mock server allows mocking the following real-server functionality:

• Verify requests' authentication (by providing AuthCredentials);
• Handle requests with GET, DELETE, POST, PUT HTTP methods;
• Handle routing by matching requests' URL (using ExactPathMatcher or RegExpPathMatcher).

Usage example

Consider this short example on how to use the API Mock Server.

Let's assume that we have the following API client with the fetchBar method we should cover with tests:

import 'package:http/http.dart' as http;

class TestClient {
  final String apiUrl;

  const TestClient(this.apiUrl);

  Future<String> fetchBar() async {
    final response = await http.get('$apiUrl/foo');

    if (response.statusCode != 200) return null;

    return response.body;
  }
}

Then, we should implement the mock server to test the desired client. The following MockServer implements the API Mock Server and mocks the behavior of the real server:

class MockServer extends ApiMockServer {
  @override
  List<RequestHandler> get handlers => [
        RequestHandler.get(
          pathMatcher: ExactPathMatcher('/foo'),
          dispatcher: _fooHandler,
        ),
      ];

  Future<void> _fooHandler(HttpRequest request) async {
    request.response.write('bar');
    
    await request.response.flush();
    await request.response.close();
  }
}

Finally, start the implemented mock server and provide the base path to the client under tests (TestClient in our case). To prevent memory leaks, close the server after all tests are finished. We should test the fetchBar method as follows:

void main() {
  group("TestClient", () {
    final mockServer = MockServer();
    TestClient client;

    setUpAll(() async {
      await mockServer.start();
      client = TestClient(mockServer.url);
    });

    tearDownAll(() async {
      await mockServer.close();
    });
    
    test(
      ".fetchBar() returns 'bar'",
      () async {
        const expectedResponse = 'bar';

        final actualResponse = await client.fetchBar();

        expect(actualResponse, equals(expectedResponse));
      },
    );
  });
}

🛡️ Guardian

Guardian is a tool designed for detecting flaky tests by analyzing JUnit XML reports and notifying the team about the results. This tool accepts the actual reports and compares them to the stored results in a database. If the test is considered flaky, Guardian notifies the team using Slack and/or Jira integrations.

Features:

• Slack integration for notifications.

🐚 Shell Words

Shell Words is a package that provides tools for parsing the command-line strings.

Features

• Parsing shell commands into words for both Windows and POSIX depending on the underlying OS (using split function).

Usage example

Consider this short example on how to use the shell words parser.

import 'package:shell_words/shell_words.dart';

void main() {
  final shellWords = split('cd foo/bar --some-flag=flag');

  print(shellWords.words); // [cd, foo/bar, --some-flag=flag]
  print(shellWords.error); // any occurred error
}

🗺️ YAML Map

YAML Map is a wrapper around Dart's yaml package that simplifies working with YAML documents.

Features

• Parsing the YAML documents to core Dart types.
• Converting Dart Maps to YAML formatted strings.

Usage example

Consider this short example on how to use the main YamlMapParser and YamlMapFormatter classes:

import 'package:yaml_map/src/yaml_map_formatter.dart';
import 'package:yaml_map/src/yaml_map_parser.dart';

void main() {
  const yaml = '''
  foo:
    bar:
      baz: 1
  ''';

  const yamlMapParser = YamlMapParser();
  final parsedYaml = yamlMapParser.parse(yaml);

  print(parsedYaml); // {foo: {bar: {baz: 1}}}
  print(parsedYaml['foo']); // {bar: {baz: 1}}
  print(parsedYaml['foo']['bar']); // {baz: 1}
  print(parsedYaml['foo']['bar']['baz']); // 1

  final yamlFormatter = YamlMapFormatter();
  print(yamlFormatter.format(parsedYaml));
  // foo: 
  //   bar: 
  //     baz: 1
}

Contributing

Consider these useful links that may help you to get started:

1. GitHub Agile process 📈
2. Dart code style 💅
3. Collaboration 🙌
4. Effective Dart 🎯

📜 License

Licensed under the terms of the Apache 2.0 License that can be found in the LICENSE file.

Consider the Dependencies Licenses document that describes the licenses for all 3-rd party libraries used in projects of this repository.