How to Contribute

How To Contribute

There are lots of ways you can contribute to the bridge project:

• File a bug/issue
• Verify fixes for bugs/issues
• Submit a bug fix or feature implementation
• Submit a feature request
• Submit additional tests
• Tell others about the WinObjC project
• Submit feedback on the project
• Submit substantive documentation edits

Code Conventions

Be sure to familiarize yourself with our coding standards before contributing code fixes.

ClangFormat

In addition to the above coding standards, code should be formatted using ClangFormat.

Automated Tests

Note: Running tests on ARM is currenctly not supported.

Running Tests

1. Build the entire solution (\build\build.sln)

2. Run <Root>\WinObjC\tests\Run-UnitTests.ps1.

Please note that this defaults to Debug; for Release, take a look at the command line parameters below.

Parameters

Defaults are in bold.

• -Verbosity [Verbose| Minimal ]

  Output verbosity.

• -Config [Debug| Release ]

  Switch between testing debug and release builds.

• -TestDirectory args

  Change the directory of tests to run. args should be a valid directory path.

• -XMLOutputDirectory args

  Change the directory to place output XML files. args should be a valid directory path. If not specified, no output files will be saved.

• -ModuleFilter args

  Run only the specified set of modules. args should be valid regex of test modules to look for.

• -TestFilter args

  Run only the specified set of tests. args should be valid regex of tests to run.

Authoring UnitTests

1. The UnitTest project is in under build\UnitTests

2. Add test code under tests\unittests and include it into the UnitTest project

3. For more info on writing the tests, see googletest samples

Functional Testing

We have developed a functional test framework for the bridge using Microsoft's TAEF and Google's GTEST. The functional test framework can run tests from inside a modern app container, thus mimicking a real UWP application, and supports using the existing GTEST UT macros and test syntax. This is accomplished by intercepting the GTEST results and redirecting them to TAEF, which then reports the results and provides logs from a UWP container.

Because Microsoft TAEF headers cannot be directly included in Objective-C files (this is being investigated), functional tests must keep their TAEF test case markup and actual test code (written in Objective-C) in two separate files.

• FunctionalTests.cpp - contains all the function test case markups that are essential for TAEF reporting.
• SampleTest.mm - contains the actual test.

Building

The FunctionalTests project file can be found under \build\Tests\FunctionalTests and is part of the main build.sln solutions file.

Adding New Tests

1. Create a new test file (or edit an existing test under tests\functionaltests\Tests) and include it in the FunctionalTests project under the Tests filter. A new test file will look like this:

#include <TestFramework.h> // <---- Automatically Includes gtest-api.h and functionaltest-api.h header for the ASSERTION/EXPECT macros
#import <Foundation/Foundation.h>

TEST(NSArray, SanityTest) {    // <---- Use Macro TEST for a test method.
    LOG_INFO("Foundation sanity test: "); <---- Simple log API

    /*** NSArray Tests (really should go into their own test at some point) ***/
    NSArray *arr1 = [NSArray arrayWithObject: @1];
    NSArray *arr2 = [NSArray arrayWithObject: @1];
    NSArray *arr3 = [NSArray arrayWithObject: @2];

    // Leveraging various ASSERT macros available in gtest-api.h
    ASSERT_TRUE_MSG([arr1 isEqual: arr2], "FAILED: arr1 and arr2 should be equal!\n");
    ASSERT_FALSE_MSG([arr1 isEqual: arr3], "FAILED: arr1 and arr2 should not be equal!\n");
    ASSERT_EQ_MSG(arr1[0], arr2[0], "FAILED: arr1[0] and arr2[0] should be equal!\n");
    ASSERT_NE_MSG(arr1[0], arr3[0], "FAILED: arr1[0] and arr3[0] should not be equal!\n");
}

Note: This is exactly how you write a Unit Test today

2. Edit tests\functionaltests\FunctionalTests.cpp to call your test.
3. If you're adding tests to an existing category, go to step 2.4. If you are adding a new category of tests, copy the code marked from the marker

```
//
// **********************************************************************************************************************
// Start Copy
// Start copying from here to add a new test category e.g. Location, URI etc.
// **********************************************************************************************************************
//
```
until
```
//
// **********************************************************************************************************************
// End Copy
// **********************************************************************************************************************
//
```

2. Give a unique name to the class and use the same name in the TEST_CLASS macro.
3. Export all the test methods and test initialization/cleanup methods. For test methods, macro TEST(_NAME1, _NAME2) in the test code translates to extern void _NAME1_NAME2(); (from the example above, TEST(NSArray, SanityTest) becomes extern void FoundationSanityTest();)
4. Use TEST_CLASS_SETUP, TEST_CLASS_CLEANUP, TEST_METHOD_SETUP and TEST_METHOD_CLEANUP macros as needed. Note these are optional macros.
5. Create a TEST_METHOD for every test you wrote in your original test file (i.e., create a TEST_METHOD for every TEST macro you created in the test code). The name should meaningfully describe the test being run.
6. TEST_METHOD should use: - TEST_METHOD_PROPERTY(L"RunAs", L"UAP") to run the test inside a UWP container. - TEST_CLASS_PROPERTY(L"UAP:Host", L"Xaml") to run under a XAML host. - TEST_CLASS_PROPERTY(L"UAP:AppXManifest", L"XYZ.AppxManifest.xml") is optional and should be used by tests that need to have special permissions set in the AppxManifest to run.

Running Functional Tests

1. Build build/build.sln. FunctionalTests.dll will be created under build\$Platform\$Config\FunctionalTests\ based on the flavor that was built.
2. Run Te.exe (located at deps\prebuilt\TAEF\TE\$Platform) from the command line:

• Te <path_to_FunctionalTests.dll> /list – list all test cases
• Te <path_to_FunctionalTests.dll> – run all tests
• Te <path_to_FunctionalTests.dll> /name:<pattern> – run a test case whose name matches the pattern specified

Note: Te.exe must be run from deps\prebuilt\TAEF\TE\$Platform for it to correctly pick up its dependencies or the path may be added to the environmental path.

Note: You can use wildcard characters to pick up a whole set of tests assuming they are named similarly.

Commit Guidance

Squash your change into 1 commit on top of the master branch.

For the commit message, follow the guide below:

The title is a ~50 character summary of the change.

After one blank line, add more detail about the change wrapped to ~80
characters. If there is a github issue that is resolved by the change,
it can be added as below, with one blank line above it.

Fix #42

Contribution License Agreement

You will need to sign a Contribution License Agreement (CLA) before submitting your pull request. To complete the CLA, you will need to submit the request via the form and then electronically sign the CLA when you receive an email containing a link to the document.

This process needs to only be done once for any Microsoft open source project.

Contributing to README and Wiki

You do not need to sign a Contribution License Agreement if you are just contributing to the README or the Wiki. However, by submitting a contribution to the README or the Wiki, you are contributing it under the Creative Commons CC0 1.0 Universal Public Domain Dedication.

Directory structure

• bin/ : Various prebuilt tools
• build/ : Projects/solutions to build the SDK
• deps/ : Open source dependencies
  • prebuilt/ : Prebuilt binaries for various architectures
• Frameworks/ : Implementation of iOS-style Frameworks
• include/ : SDK headers (including headers for iOS-style Frameworks)
  • Platform/ : Headers for Windows Objective-C bindings for various OS versions
• msvc/ : Visual Studio integration files
• samples/ : Assorted samples
• tools/ : Source code to tools

Pull Request Flow

• Please ensure that you fork the winobjc repository and work there before submitting a pull request. This way, your updates based on codereview or other feedback show up as updates in the same pull request.
• Submit all pull requests to develop branch.

Pre-request checklist

Please ensure the following before submitting a pull request for your changes:

• You have signed the CLA and adhered to it.
• The entire solution (\build\build.sln) builds with no errors for all flavors.
• The changed code follows our code conventions.
• The code is formatted using ClangFormat.
• New tests have been added for all new features.
• All of the automated tests pass with no failures.

After submitting a request

What happens after a pull request is submitted?

• WinObjC team reviews the change, and checks for code convention or any other issues.

• WinObjC team verifies the change passes build and automated tests with no errors.

• If the above looks good, the pull request will be accepted, and the change will be merged into the master branch. Otherwise, we will iterate over the changes with the contributor to work through any issues before accepting the pull request.