From ea7eee5abf476965c7b96eb531ac19614767efef Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:17:50 -0500 Subject: [PATCH 1/9] improves readme and adds contributing guide --- CONTRIBUTING.md | 29 +++++++++++++++ README.md | 97 ++++++++++++++++++++++++++++++++----------------- 2 files changed, 93 insertions(+), 33 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..31a8750 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,29 @@ +# Contributing Guide + +Thank you for considering contributing to near-directory! Here are some guidelines to help you get started. + +## Getting Started + +To contribute to near-directory, follow these steps: + +1. Fork the repository on GitHub. +2. Clone your forked repository to your local machine. +3. Make your changes locally. +4. Test your changes to ensure they work as expected. +5. Commit your changes with descriptive commit messages. We like [Semantic Commit Messages](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716). +6. Push your changes to your fork on GitHub. +7. Create a pull request to the main repository. + +## Code Style + +Please follow the existing code style and conventions used in the project. + +## Testing + +This repository uses playwright tests, which can be found in [/tests](./tests/). Ensure that your changes include appropriate tests and that existing tests pass. + +## Submitting Issues + +If you encounter any issues or have feature requests, please submit them through GitHub issues. Include as much detail as possible to help us understand and address the problem efficiently. + +Thank you for your interest in contributing to near-directory! Your contributions are greatly appreciated. diff --git a/README.md b/README.md index e92e053..67d66a7 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,35 @@ -# Near Directory - -- Old Version: [Near Catalog](https://dev.near.org/nearcatalog.near/widget/Index) -- Designs: [Figma](https://www.figma.com/design/I9qRE8BQA8dfFYyYrFRnnm/NBH-Ongoing-Design-Files?node-id=245-2&t=KbwqZF8zbf7uFCt4-0) -- Live Demo: [Near Directory](https://near-directory-nextjs.vercel.app/) - -This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). + + + + + +
+ +near landscape +
+
+

+ Ecosystem directory for NEAR Protocol. +

+ +
+ +
+ Table of Contents + +- [Getting Started](#getting-started) + - [Cloning the repo](#cloning-the-repo) + - [Installing dependencies](#installing-dependencies) + - [Running the app](#running-the-app) +- [Project Structure](#project-structure) + - [Routes](#routes) + - [Global State](#global-state) +- [Contributing](#contributing) + +
## Getting Started -### Cloning the repo - -```bash -git clone https://github.com/NEARBuilders/near-directory-nextjs.git -``` - ### Installing dependencies ```bash @@ -28,38 +44,53 @@ First, run the development server: npm run dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +Open [http://localhost:3000](http://localhost:3000) in your browser to see the result. + +### Building for production + +```bash +npm build +``` -This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font. +### Running tests -## Routes +```bash +npm test +``` -The routes are defined in the `app` folder. There are three main pages: +## Project Structure -- `/`: This is the home page of the application. It displays a list of projects that are available on the NEAR platform. -- `/project/:projectId`: This is the page that displays the details of a specific project. It includes information about the project, such as the name, description, and the list of tags associated with the project. -- `/category/:categoryId`: This is the page that displays a list of projects that are associated with a specific category. +This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load [Inter](https://fonts.google.com/specimen/Inter), a custom Google Font. -## Global State +### Routes -[zustand](https://github.com/pmndrs/zustand) is used to manage global state. It is a state management library that provides a simple and scalable solution for managing application state in a React or Preact application. +This project uses the [Next.js App Router](https://nextjs.org/docs/app), and so the routes are defined in the `app` folder. There are three main pages: -The state is stored in the `store` folder. There are two stores that are used in this project: +- `/`: Home page of the application. It displays a list of projects that are available on the NEAR platform. +- `/project/:projectId`: Displays the details of a specific project. It includes information about the project, such as the name, description, and the list of tags associated with the project. +- `/category/:categoryId`: Displays a list of projects that are associated with a specific category. -- `search-store.ts`: This store manages the search state, including the search query and the tags that are selected. -- `tags-modal-store.ts`: This store manages the state of the tags modal for mobile devices. +### Global State -## Learn More +[zustand](https://github.com/pmndrs/zustand) is used to manage global state. It is a state management library that provides a simple and scalable solution for managing application state in a React or Preact application. -To learn more about Next.js, take a look at the following resources: +The state is stored in the `store` folder. There are two stores that are used in this project: -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +- `search-store.ts`: Manages the search state, including the search query and the tags that are selected. +- `tags-modal-store.ts`: Manages the state of the tags modal for mobile devices. -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! +## Contributing -## Deploy on Vercel +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +If you're interested in contributing to this project, please read the [contribution guide](./CONTRIBUTING). -Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. +
+ +Near Builders + +
From 41a3c689e6cbe5a66f0d34e061d40b38a0d44b4a Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:32:59 -0500 Subject: [PATCH 2/9] rearranges tests, adds testing guide, adds workflow --- .github/workflows/continuous-integration.yml | 38 +++++++++++ .github/workflows/playwright.yml | 27 -------- CONTRIBUTING.md | 2 +- README.md | 13 ++-- package.json | 2 + playwright-tests/README.md | 65 +++++++++++++++++++ .../tests}/category.spec.ts | 0 .../tests}/home.spec.ts | 0 .../tests}/project.spec.ts | 0 playwright.config.ts | 2 +- 10 files changed, 116 insertions(+), 33 deletions(-) create mode 100644 .github/workflows/continuous-integration.yml delete mode 100644 .github/workflows/playwright.yml create mode 100644 playwright-tests/README.md rename {tests => playwright-tests/tests}/category.spec.ts (100%) rename {tests => playwright-tests/tests}/home.spec.ts (100%) rename {tests => playwright-tests/tests}/project.spec.ts (100%) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml new file mode 100644 index 0000000..112d761 --- /dev/null +++ b/.github/workflows/continuous-integration.yml @@ -0,0 +1,38 @@ +name: CI +on: + pull_request: + push: + branches: + - main + +jobs: + prettier: + name: Prettier + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 20 + cache: "npm" + - name: Install dependencies + run: npm install --frozen-lockfile + - name: Run code formatting check + run: npm run fmt:check + playwright-tests: + name: Playwright tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 20 + cache: "npm" + - name: Install dependencies + run: | + npm add bos-workspace + npm playwright install-deps + npm playwright install + - name: Run tests + run: | + npm playwright test \ No newline at end of file diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml deleted file mode 100644 index 467190b..0000000 --- a/.github/workflows/playwright.yml +++ /dev/null @@ -1,27 +0,0 @@ -name: Playwright Tests -on: - push: - branches: [ main, master ] - pull_request: - branches: [ main, master ] -jobs: - test: - timeout-minutes: 60 - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: lts/* - - name: Install dependencies - run: npm ci - - name: Install Playwright Browsers - run: npx playwright install --with-deps - - name: Run Playwright tests - run: npx playwright test - - uses: actions/upload-artifact@v4 - if: always() - with: - name: playwright-report - path: playwright-report/ - retention-days: 30 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 31a8750..27b33f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ Please follow the existing code style and conventions used in the project. ## Testing -This repository uses playwright tests, which can be found in [/tests](./tests/). Ensure that your changes include appropriate tests and that existing tests pass. +This repository uses playwright tests, which can be found in [/playwright-tests](./playwright-tests/). Ensure that your changes include appropriate tests and that existing tests pass. ## Submitting Issues diff --git a/README.md b/README.md index 67d66a7..55a732c 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,10 @@ Table of Contents - [Getting Started](#getting-started) - - [Cloning the repo](#cloning-the-repo) - [Installing dependencies](#installing-dependencies) - [Running the app](#running-the-app) + - [Building for production](#building-for-production) + - [Running tests](#running-tests) - [Project Structure](#project-structure) - [Routes](#routes) - [Global State](#global-state) @@ -49,18 +50,22 @@ Open [http://localhost:3000](http://localhost:3000) in your browser to see the r ### Building for production ```bash -npm build +npm run build ``` ### Running tests ```bash -npm test +npm run test ``` +See the full [testing guide](./playwright-tests/README.md). + ## Project Structure -This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load [Inter](https://fonts.google.com/specimen/Inter), a custom Google Font. +This is a [Next.js](https://nextjs.org/) project bootstrapped with [create-next-app](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). + +It uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load [Inter](https://fonts.google.com/specimen/Inter), a custom Google Font. ### Routes diff --git a/package.json b/package.json index 39ad5fc..e912d3b 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,8 @@ "build": "next build", "start": "next start", "lint": "next lint", + "test": "npx playwright test", + "test:ui": "npx playwright test --ui", "fmt": "prettier --write .", "fmt:check": "prettier --check ." }, diff --git a/playwright-tests/README.md b/playwright-tests/README.md new file mode 100644 index 0000000..1633b86 --- /dev/null +++ b/playwright-tests/README.md @@ -0,0 +1,65 @@ +# Testing Guide + +This project uses [playwright](https://playwright.dev/) for end-to-end testing. Please become familiar with this documentation. + +## Writing tests + +Tests should be written for each change or addition to the codebase. +If a new feature is introduced, tests should be written to validate its functionality. If a bug is fixed, tests should be written to prevent regression. Writing tests not only safeguards against future breaks by other developers but also accelerates development by minimizing manual coding and browser interactions. + +When writing tests, remember to: + +- Test user-visible behavior +- Make tests as isolated as possible +- Avoid testing third-party dependencies + +> **[LEARN BEST PRACTICES](https://playwright.dev/docs/best-practices)** + +See the [cookbook](#cookbook) for help in covering scenerios. It is possible to [generate tests](https://playwright.dev/docs/codegen) via the [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright). + +## Running tests + +To run the tests, you may do so through the command line: + +```cmd +npm run test +``` + +With playwright's interactive testing UI: + +```cmd +npm run test:ui +``` + +Or through VS Code, see [Getting started - VS Code](https://playwright.dev/docs/getting-started-vscode). + +## Recording video + +You may automatically record video with your tests by setting + +``` +use: { + video: "on" +} +``` + +in the [playwright.config.js](../playwright.config.js). After running tests, you will find the output as a `.webm` in `./test-results`. Then, [convert to MP4](https://video.online-convert.com/convert/webm-to-mp4) and share. + +It is encouraged to include video in pull requests in order to demonstrate functionality and prove thorough testing. + +## Cookbook + +### Mocking fetch requests + +If you are testing a component that makes fetch requests, you can mock them using the [fetch](https://playwright.dev/docs/api/class-fetch) API. + +```javascript +await page.route("**/api/hello", (route) => { + return route.fulfill({ + status: 200, + body: "Hello, World!", + }); +}); +``` + +Currently, we add this to the `beforeEach` hook in the test file. This way we do not have to mock the requests for every test. diff --git a/tests/category.spec.ts b/playwright-tests/tests/category.spec.ts similarity index 100% rename from tests/category.spec.ts rename to playwright-tests/tests/category.spec.ts diff --git a/tests/home.spec.ts b/playwright-tests/tests/home.spec.ts similarity index 100% rename from tests/home.spec.ts rename to playwright-tests/tests/home.spec.ts diff --git a/tests/project.spec.ts b/playwright-tests/tests/project.spec.ts similarity index 100% rename from tests/project.spec.ts rename to playwright-tests/tests/project.spec.ts diff --git a/playwright.config.ts b/playwright.config.ts index 7e96ffd..365f4b3 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -11,7 +11,7 @@ import { defineConfig, devices } from "@playwright/test"; * See https://playwright.dev/docs/test-configuration. */ export default defineConfig({ - testDir: "./tests", + testDir: "./playwright-tests/tests", /* Run tests in files in parallel */ fullyParallel: true, /* Fail the build on CI if you accidentally left test.only in the source code. */ From 405d296b231ff2517483481476748a6b3f1bf914 Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:35:41 -0500 Subject: [PATCH 3/9] fmt --- .github/workflows/continuous-integration.yml | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 112d761..c04b81a 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -35,4 +35,4 @@ jobs: npm playwright install - name: Run tests run: | - npm playwright test \ No newline at end of file + npm playwright test diff --git a/README.md b/README.md index 55a732c..855d884 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ - [Routes](#routes) - [Global State](#global-state) - [Contributing](#contributing) - + ## Getting Started From 3b4d591014c6ecd795012ee42bc80ba868ca3191 Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:43:14 -0500 Subject: [PATCH 4/9] add caching --- .github/workflows/continuous-integration.yml | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index c04b81a..6546713 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -24,15 +24,14 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/cache@v3 + id: playwright-cache with: - node-version: 20 - cache: "npm" + path: | + ~/.cache/ms-playwright + key: ${{ runner.os }}-playwright-${{ hashFiles('**/package-lock.json') }} - name: Install dependencies - run: | - npm add bos-workspace - npm playwright install-deps - npm playwright install + run: npx playwright install --with-deps chromium + if: steps.playwright-cache.outputs.cache-hit != 'true' - name: Run tests - run: | - npm playwright test + run: npx playwright test From ffb0017ab5b6f64286343672627b4bdb52d7e4fb Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:48:21 -0500 Subject: [PATCH 5/9] run tests --- .github/workflows/continuous-integration.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 6546713..145d69f 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -34,4 +34,4 @@ jobs: run: npx playwright install --with-deps chromium if: steps.playwright-cache.outputs.cache-hit != 'true' - name: Run tests - run: npx playwright test + run: npm run test From 64b4c8d2e2c9225920a110bc76be2af68c4978a4 Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:50:53 -0500 Subject: [PATCH 6/9] adds node --- .github/workflows/continuous-integration.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 145d69f..b07b734 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -24,6 +24,10 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 20 + cache: "npm" - uses: actions/cache@v3 id: playwright-cache with: From f7d654bc4316a3e7e558d1b69e6a013a916be84f Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:54:08 -0500 Subject: [PATCH 7/9] adjust --- .github/workflows/continuous-integration.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index b07b734..559ca88 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -35,7 +35,10 @@ jobs: ~/.cache/ms-playwright key: ${{ runner.os }}-playwright-${{ hashFiles('**/package-lock.json') }} - name: Install dependencies - run: npx playwright install --with-deps chromium + run: | + npx playwright install-deps + npx playwright install if: steps.playwright-cache.outputs.cache-hit != 'true' - name: Run tests - run: npm run test + run: | + npx playwright test From ebdd9163bdda2a85dfe9c72a366b7496aabdac0d Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 15:56:10 -0500 Subject: [PATCH 8/9] isntall deps --- .github/workflows/continuous-integration.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 559ca88..9f96598 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -34,6 +34,8 @@ jobs: path: | ~/.cache/ms-playwright key: ${{ runner.os }}-playwright-${{ hashFiles('**/package-lock.json') }} + - name: Install dependencies + run: npm ci - name: Install dependencies run: | npx playwright install-deps From 25b94f1487c04ce9d2f21c11273d17ceb6adfbec Mon Sep 17 00:00:00 2001 From: Elliot Braem <16282460+elliotBraem@users.noreply.github.com> Date: Mon, 5 Aug 2024 16:00:18 -0500 Subject: [PATCH 9/9] config more workers --- playwright.config.ts | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/playwright.config.ts b/playwright.config.ts index 365f4b3..8204cad 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -18,10 +18,9 @@ export default defineConfig({ forbidOnly: !!process.env.CI, /* Retry on CI only */ retries: process.env.CI ? 2 : 0, - /* Opt out of parallel tests on CI. */ - workers: process.env.CI ? 1 : undefined, + workers: process.env.CI ? "100%" : undefined, /* Reporter to use. See https://playwright.dev/docs/test-reporters */ - reporter: "html", + reporter: "line", /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */ use: { /* Base URL to use in actions like `await page.goto('/')`. */ @@ -37,7 +36,6 @@ export default defineConfig({ name: "chromium", use: { ...devices["Desktop Chrome"] }, }, - { name: "firefox", use: { ...devices["Desktop Firefox"] }, @@ -68,6 +66,7 @@ export default defineConfig({ // use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // }, ], + outputDir: "test-results/", /* Run your local dev server before starting the tests */ webServer: {