Merge pull request #22 from NEARBuilders/doc/readme

Updates README, Contributing guide, testing guide

.github/workflows/continuous-integration.yml

@@ -0,0 +1,46 @@
+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"
+      - uses: actions/cache@v3
+        id: playwright-cache
+        with:
+          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
+          npx playwright install
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+      - name: Run tests
+        run: |
+          npx playwright test

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 [/playwright-tests](./playwright-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.

README.md

@@ -1,18 +1,35 @@
-# Near Directory
+<!-- markdownlint-disable MD014 -->
+<!-- markdownlint-disable MD033 -->
+<!-- markdownlint-disable MD041 -->
+<!-- markdownlint-disable MD029 -->
 
-- 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/)
+<div align="center">
 
-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).
+<img src="https://near-directory-nextjs.vercel.app/_next/static/media/logo.0c496378.svg" alt="near landscape" height="100" />
+<br />
+<br />
+  <p>
+    <strong>Ecosystem directory for <a href="https://near.org/" target="_blank">NEAR Protocol</a>.</strong>
+  </p>
 
-## Getting Started
+</div>
 
-### Cloning the repo
+<details>
+  <summary>Table of Contents</summary>
 
-```bash
-git clone https://github.com/NEARBuilders/near-directory-nextjs.git
-```
+- [Getting Started](#getting-started)
+  - [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)
+- [Contributing](#contributing)
+
+</details>
+
+## Getting Started
 
 ### Installing dependencies
 
@@ -28,38 +45,57 @@ 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 run build
+```
+
+### Running tests
 
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
+```bash
+npm run test
+```
 
-## Routes
+See the full [testing guide](./playwright-tests/README.md).
 
-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 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).
 
-## Global State
+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.
 
-[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.
+### Routes
 
-The state is stored in the `store` folder. There are two stores that are used in this project:
+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:
+
+- `/`: 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.
+<div align="right">
+<a href="https://nearbuilders.org" target="_blank">
+<img
+  src="https://ipfs.near.social/ipfs/bafkreiavh7rnvf4zzb5rjohul7xwrlgz4y6ysdtmdsvpjeqpjtmuvgal7a"
+  alt="Near Builders"
+  height="40"
+/>
+</a>
+</div>

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 ."
   },

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.

playwright.config.ts

@@ -11,17 +11,16 @@ 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. */
   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: {