{"id":16461744,"url":"https://github.com/marabesi/testable","last_synced_at":"2025-03-16T18:31:25.706Z","repository":{"id":36236556,"uuid":"136395473","full_name":"marabesi/testable","owner":"marabesi","description":"Testable - gamified tool to improve unit testing teaching","archived":false,"fork":false,"pushed_at":"2024-09-21T02:22:54.000Z","size":80820,"stargazers_count":20,"open_issues_count":23,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-11T11:45:56.352Z","etag":null,"topics":["github-page","jest-tests","learning","react-components","testing","unittesting"],"latest_commit_sha":null,"homepage":"https://marabesi.github.io/testable","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marabesi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-06T23:09:46.000Z","updated_at":"2024-06-22T16:08:26.000Z","dependencies_parsed_at":"2024-06-22T17:48:02.704Z","dependency_job_id":"d89e92b4-7fb7-4eb0-afc6-4bb9e571739b","html_url":"https://github.com/marabesi/testable","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marabesi%2Ftestable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marabesi%2Ftestable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marabesi%2Ftestable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marabesi%2Ftestable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marabesi","download_url":"https://codeload.github.com/marabesi/testable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243826788,"owners_count":20354220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-page","jest-tests","learning","react-components","testing","unittesting"],"created_at":"2024-10-11T11:09:13.741Z","updated_at":"2025-03-16T18:31:23.916Z","avatar_url":"https://github.com/marabesi.png","language":"TypeScript","readme":"[![Codacy Badge](https://app.codacy.com/project/badge/Grade/6df65172ce484aec85691c7f0e354d9a)](https://www.codacy.com/gh/marabesi/testable/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=marabesi/testable\u0026amp;utm_campaign=Badge_Grade)\n[![Node CI](https://github.com/marabesi/testable/actions/workflows/pipeline.yml/badge.svg)](https://github.com/marabesi/testable/actions/workflows/pipeline.yml)\n[![Coverage Status](https://coveralls.io/repos/github/marabesi/testable/badge.svg?branch=master)](https://coveralls.io/github/marabesi/testable?branch=master)\n\n## Testable - gamified tool to improve unit testing teaching\n\nTestable is a gamified tool that offers a javascript based challenges aimed to\nteach unit testing.\n\n![Testable intro](concept.gif \"Testable\")\n\n## Code base visualization\n\nThis is a visualization built using [this project](https://github.com/githubocto/repo-visualizer-demo), it\nhelps us to understand how the code base and gives a hint on where the\ncomplex part is.\n\n![Visualization of this repo, based on https://github.com/githubocto/repo-visualizer-demo](./diagram.svg)\n\n## Table of contents\n\n1. [Project structure](#1-project-structure)\n2. [Installation](#2-installation)\n3. [Firebase](#3-firebase)\n4. [Components documentation (styleguidist)](https://marabesi.github.io/testable/docs)\n5. [Publications](#4-publications)\n\n## 1. Project structure\n\nThis repository host the testable web app and the ranking api. Both are\nin the same repository for convenience and for a simpler approach\nfor local development with docker.\n\n```\n|_\n  |_ docker        -\u003e files used to configure change docker configuration\n  |_ webapp        -\u003e the front end app is in this folder\n  |_ ranking-api   -\u003e the ranking api is here\n  |_ .env          -\u003e this file is used to manage env variables for both projects\n```\n\nThe front end app is built using the following libraries:\n\n1. React (with typescript)\n2. Redux\n3. Code mirror\n4. React router\n5. React Intl\n6. Introjs / introjs React wrapper\n7. Firebase and Firebase UI\n\nThe ranking api is a node js + express application and uses the following libraries:\n\n1. dotenv\n2. express\n3. firebase-admin\n\nEach folder has its own readme file with more detail about the project it self.\n\n- [webapp readme](webapp/README.md)\n- [ranking api readme](ranking-api/README.md)\n\n## 2. Installation\n\nTestable uses firebase to manage users and its data, which makes a firebase\naccount a requirement to get the project up and running. The webapp\nrequires the firebase JSON from the firebase console, and the ranking\napi requires the firebase json generated by the google account.\n\nThe recommended approach to use the application is through docker and docker-compose.\nVariables are configured using a `.env` in the root folder of the project.\n\nThe most basic `.env` file is as follows:\n\n```\n# exposes the webapp and ranking api in the following ports:\nRANKING_PORT=4000\nTESTABLE_PORT=3000\n\n# variables used on the webapp only\nREACT_APP_FIREBASE_JSON={\"apiKey\":\"\",\"authDomain\":\"\",\"databaseURL\":\"\",\"projectId\":\"\",\"storageBucket\":\"\",\"messagingSenderId\":\"\",\"appId\":\"\"}\nREACT_APP_RANKING_API=http://localhost:4000\nREACT_APP_DEBUG=false\nREACT_APP_SHOW_SURVEY=false\nREACT_APP_SURVEY_URL=http://my_form_to_be_used.com\nREACT_APP_BASE_NAME=/\n\n# variables used on the ranking api only\nRANKING_FIREBASE_JSON={\"type\": \"service_account\", \"project_id\": \"\", \"private_key_id\": \"\", \"private_key\": \"\", \"client_email\": \"\", \"client_id\": \"\", \"auth_uri\": \"\", \"token_uri\": \"\", \"auth_provider_x509_cert_url\": \"\", \"client_x509_cert_url\": \"\"}\nFIREBASE_DATABASE_URL=https://my_database.firebaseio.com\nCORS_ORIGINS=localhost:3000,localhost:4000\n```\n\nThe following table gives more details about each one of them. For each\nof the variables, if more detail is needed a link is provided.\n\n| Variable                | Required | Description                                                                                                                                                                                                                                                                                                  |\n|-------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| RANKING_PORT            | true    | this is the port in which you want to expose the ranking api                                                                                                                                                                                                                                                 |\n| TESTABLE_PORT           | true    | this is the port in which you want to expose the front end / web app                                                                                                                                                                                                                                         |\n| REACT_APP_FIREBASE_JSON | true    | Plain JSON provided by the Firebase console                                                                                                                                                                                                                                                                  |\n| REACT_APP_HOST          | false   | host used to share the achievements in the social media                                                                                                                                                                                                                                                      |                                                                                                                                                                                                                                                       |\n| REACT_APP_RANKING_API   | true    | The URL from the ranking API. For example, if the `RANKING_PORT` is 4000, this value would be `http://ranking:4000` - `ranking:4000` comes from the docker network.                                                                                                                                          |\n| REACT_APP_DEBUG         | false   | The debug mode in the interface allows a fast travel in time and debug messages through the dev tool. This value should be used in local/development mode only                                                                                                                                               |\n| REACT_APP_SHOW_SURVEY   | false   | Variables that controls if the survey button show be shown.                                                                                                                                                                                                                                                  |\n| REACT_APP_SURVEY_URL    | false   | If `REACT_APP_SHOW_SURVEY` is set to true, then this URL is displayed for the user to fill in the survey.                                                                                                                                                                                                    |\n| PUBLIC_URL              | false   | This is the full URL where the frontend is running, for example: `https://app-testable.herokuapp.com`                                                                                                                                                                                                        |\n| REACT_APP_BASE_NAME     | false   | this variable is used most for deployment purposes. It configures the build step to use a different base name than `/`. This is useful for deployments under sub directories in the domain, for example: `https://mydomain.org/app`.                                                                         |\n| RANKING_FIREBASE_JSON   | true    | Plain json provided by the Firebase services account                                                                                                                                                                                                                                                         |\n| FIREBASE_DATABASE_URL   | true    | This value is provided by the firebase console JSON, and the value is under the key `databaseURL`. Both values should match, to prevent authentication issues.                                                                                                                                               |\n| CORS_ORIGINS            | false   | This is the variable that controls the CORS in the ranking API. The value should be the domain name and the port if needed. Valid values are: `localhost` or `localhost:3000`. Multiple values are accepted and they must be split by comma, such as: `mydomain1.com,mydomain2.com,localhost:3000,localhost` |\n\nOnce the `.env` file is in place and has the described variables/values,\nthe docker services are ready to run.\n\n### 2.1 Development mode\n\nThis project comes with two docker compose files, one for development and another\none for deployment. For development the suggested approach is to run:\n\n```\ndocker-compose -f docker-compose-dev.yml up\n```\n\nThis will spin up four services three services, names:\n\n1. The web app (front end)\n2. the web app documentation\n3. The ranking api\n\nThose are reloaded once the source code is changed. Perfect for development.\n\n### 2.2 Testing installation (development mode)\n\nThe project provides a test command to check the installation:\n\n```\ndocker-compose -f docker-compose-dev.yml run --rm testable npm run coverage -- --watchAll=false\n```\n\n### 2.3 Deployment mode\n\nThe other option is the deployment mode, which uses the default file `docker-compose.yml`.\nThere are two differences for this mode. The first one is that it runs without\nauto reloading once the source code is changed and the other one is that\nthe documentation is built in the web app distribution rather than having its own service.\n\n```\ndocker-compose up\n```\n\n## 3. Firebase\n\nAs previously mentioned this project uses firebase for managing users and\neverything related to authentication. This hard dependency makes a must,\nthe firebase account. This project uses both JSON generated by Firebase,\nthe one via [firebase console](https://console.firebase.google.com) and\nthe one generated by [the services account](https://firebase.google.com/docs/admin/setup).\n\n## 4. Publications\n\n- [Towards a Gamified Tool to Improve Unit Test Teaching](https://ieeexplore.ieee.org/abstract/document/8994972)\n- [EVALUATION OF TESTABLE, A GAMIFIED TOOL TO IMPROVE UNIT TEST TEACHING](https://library.iated.org/view/MARABESI2020EVA)\n- [Testable: uma ferramenta gamificada para auxiliar o ensino de testes unitários](https://loja.editoradialetica.com/loja/produto.php?loja=791959\u0026IdProd=1244243593\u0026iniSession=1\u0026623b524a82509)\n\n## 5. Related resources\n\n- [The effects of personalized gamification on students’ flow experience, motivation, and enjoyment](https://link.springer.com/article/10.1186/s40561-022-00194-x)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarabesi%2Ftestable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarabesi%2Ftestable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarabesi%2Ftestable/lists"}