flexadminportal

Welcome to the official repository for the fLEX Admin Portal. This repository contains the source code for the fLEX Admin Portal, the backend and administration for the fLEX testing system.

To visit the compiled site, please see the develop site or the production site.

Frontend Development

1. Install the Node.js dependencies yarn
2. Start the development server with yarn web

API Development

1. Log in to the UTIA organization in the AWS console (using your AWS console link).
2. amplify checkout env dev
3. amplify pull to get the latest changes from the AWS backend. The latest amplify folder should be committed regularly to the git branch with the same name as the amplify env (for feature previews with accompanying amplify changes). When a pull request is merged into develop or main, the dev or main environment's latest changes should be committed to the develop or main branch in our git repository. For these reasons, when running amplify pull, it is likely that your environment is already up-to-date.
4. If your feature requires backend changes, create a temporary amplify env by the name of your feature branch. For example, if you have a new feature to add an API category for annual weather, you might want to name your branch "annual_weather." On git, your full branch name is feature/annual_weather. On amplify, create an env with an intuitive matching name, such as annual_weather. To do this amplify env checkout annual_weather.
5. Edit the files for your backend feature in the amplify folder.
6. amplify push to provision and test your resources.

Note that amplify mock is not supported with our project because it uses an RDS datastore.

Lambda Development

1. Perform the above steps 1-4 to set up the amplify environment.
2. Setup a python venv for Lambda functions python3.11 -m venv venv && source venv/bin/activate
3. Install the Python dependencies pip install mysql-connector-python

Testing

End user and component testing uses the Cypress library. By accepting your invitation to the Cypress project for the fLEX Admin Portal, you will be able to view videos of test runs and results. To log in to Cypress, simply npx cypress open, select "Log In" and follow the prompts.

Writing Tests

Components and Views

When you create a new component or view, developers must write a test for it. Name view tests by the view name followed by .cy.tsx. For example, the test for the Home view is Home.cy.tsx. Name component tests by the name "index" followed by the component name followed by .cy.tsx. For example, the test for the FLEXButton component is indexFLEXButton.cy.tsx.

A basic unit test for the React component should start by testing rendering of the component. For example, in indexFLEXButton.cy.tsx:

import React from "react"
import FLEXButton from "../app/View/Components/FLEXButton/index"

describe("<FLEXButton />", () => {
    it("renders", () => {
        cy.mount(
            <FLEXButton />
        )
    })

    // Add more tests here...
})
Copy

For an example of test coverage in components, see indexFLEXCard.cy.tsx. You should cover the configurable props and the component's behavior in response to those props.

For more details on writing tests, see the Cypress React component docs page.

End User Tests

End user test spec files are located in the Cypress e2e folder. These tests are written in TypeScript and use the Cypress API to interact with the application. For example, in auth.spec.cy.ts:

describe("auth end-to-end tests", () => {
    const baseUrl = Cypress.env("BASE_URL")

    beforeEach(() => {
        cy.visit(baseUrl)
    })

    it("should display the email and password fields", () => {
        cy.get("input[type=password]").should("exist")
        cy.get("input[type=email]").should("exist")
    })

    // ... more tests (see file for full example)
})
Copy

For more details on writing end user tests, see the Cypress end-to-end testing docs page.

Running Tests

Running end user tests requires the application to be running. To run the application, use yarn web in one terminal and yarn test:e2e in another terminal. Running component tests does not require the application to be running.

• Run all tests with yarn test
• Run the end user tests with yarn test:e2e
• Run the component tests with yarn test:cmp

Recording test runs to the Cypress cloud:

All tests are ran and recorded automatically in our CI/CD flow for the develop and main branches. To record a test run manually, you can run the following commands:

Run any of the testing commands with :record at the end. For example, yarn test:e2e:record will record the end user tests for other Cypress users in our organization to review.

Failed recorded test cases send a notification to our Slack channel to alert developers of the failure.

Testing builds

To test the production build locally, yarn s will build and serve the compiled site. This is useful for testing the production build locally before deploying.

Serving uses the "serve" npm package. When you run yarn s, serve will give you a link to the local server. Open this link in your web brower to view a test run of the production build.

Documentation

For more information on the fLEX Admin Portal, see the fLEX Admin Portal documentation. This README file will be used as the front page for the documentation site.

Docs are generated by typedoc and use tsdoc comments from the source code (currently only Model and ViewModel produce meaninfgul docs).

To generate docs, run yarn document and open the generated index.html file in the docs folder in your browser. To deply the docs, run yarn deploy:docs.