Developer Documentation - milannair/LetsMeet GitHub Wiki

Obtaining the Source Code

The files in this repository are the only ones you need to build both the backend and the frontend. You do not need to care about any submodules or external repositories.

The easiest way to obtain those files is to clone this repository using Git:

$ git clone https://github.com/milannair/LetsMeet

Directory Structure

  • api: code for the backend server
    • server/controllers: controllers that send and receive data to and from the database
    • server/models: the data models that correspond to the documents on the database in MongoDB
    • __tests__: unit tests
  • frontend: code for the frontend app
    • assets: resource files like images
    • components: React Native UI components to use in screens
    • controllers: controllers that send and receive data to and from the backend API
    • enums: enum classes
    • hooks: hooks useful for websocket
    • models: data models that correspond to documents in the MongoDB database
    • navigation: navigation system for our application
    • screens: React Native UI screens to house any number of components
    • __tests__: unit tests
    • App.js: React Native entry point (parent component)
  • scripts: useful scripts for the building and developing process
  • init.sh: the init script that creates the api/.env file, which stores database credentials
  • README.md: the README file for GitHub repository
  • Some hidden files and directories start with .: configuration files for Git, GitHub, CI, etc.
  • reports: weekly reports for CSE 403 - please ignore this directory for development purposes

Building the Software

Our project uses JavaScript and Node.js, so it can run directly without any compilation. However, you need to install dependency packages with npm before running it.

To set up the project, you may follow the installation instruction in our User Documentation.

After that, to run backend and frontend, change your working directory to api and frontend respectively, and run npm start.

Configuring the Software for Development Purposes

By default, the backend uses the MongoDB Cluster we created for this project. You might want to use your own database for debugging and testing purposes. In this case, modify the following line in file api/.env to let the backend use the local MongoDB database running on mongodb://localhost:27017:

  DB_USERNAME=dev
  DB_PW=devpass
- USE_LOCAL_DB=false
+ USE_LOCAL_DB=true
  ACCESS_TOKEN=peerKey

To learn more about installing MongoDB on your machine, please refer to the official MongoDB Community Edition installation tutorials.

Testing the Software

To run automated tests for the backend and frontend, go to the api and frontend directories respectively and run npm test.

Adding New Tests

We use Jest for our testing framework on both backend and frontend. You can learn more about Jest on their official website.

All test files should have their file name end with .test.js. Backend and frontend tests should be put into api/__tests__ and frontend/__tests__ respectively.

To add your own tests, you may look at existing tests in those directories to get started. The backend tests use axios to make HTTP requests to the API and Jest's assertion functions to verify results returned by the API. The frontend tests perform snapshot testing with Jest to check the UI's consistency.

Notes for Backend Tests

Under api/__tests__, you can find a directory called non_tests. This directory contains files that are useful for unit tests:

  • constants.js: helpful constants that can be used in the tests
  • globalSetup.js: code that will be run once before all tests
  • setup.js: set-up and tear-down functions for every single test file
  • variables.js: variables whose value is unknown until the runtime of the tests

Unless you know what you are doing, please do not modify files in this directory; otherwise, existing tests could be broken. In addition, please do not add your new tests to this directory because they will be ignored.

Notes for Frontend Tests

After you have added new frontend tests, you should create their test snapshots and check them into Git per Jest's official suggestion:

The snapshot artifact should be committed alongside code changes, and reviewed as part of your code review process.

To generate snapshots, just run npm test in the frontend directory. After that, you can add those snapshots to Git.

$ basename $(pwd) # Make sure you are in the 'frontend' directory
frontend
$ npm test
(Test output omitted)

Snapshot Summary
 › x snapshots written from y test suites.

(Test summary omitted)
$ git add __tests__
$ git commit

Once the snapshots are generated, they will be used in future tests for checking if the UI has been accidentally changed. If you intend to make a UI change and the change causes any test to fail, then you should update the test snapshots with command npm test -- -u. As always, add the new snapshots to Git after the command completes.

$ npm test -- -u
(Test output omitted)

Snapshot Summary
 › x snapshots updated from y test suites.

(Test summary omitted)
$ git add __tests__
$ git commit

Building a Release of the Software

This project uses the rolling release model, so you cannot build a point release of the software at this point. The head of the master branch is always the latest version of the app.