From 7af807e5f739e79ccb874d765158c333a01c79c0 Mon Sep 17 00:00:00 2001 From: Joost Date: Wed, 20 Dec 2023 14:40:30 +0000 Subject: [PATCH 1/2] Add "test the client" to v5 recipes --- .../testing-the-client.md | 144 ++++++++++++++++++ mkdocs.yml | 4 +- 2 files changed, 147 insertions(+), 1 deletion(-) create mode 100644 docs/recipes/developing-and-testing/testing-the-client.md diff --git a/docs/recipes/developing-and-testing/testing-the-client.md b/docs/recipes/developing-and-testing/testing-the-client.md new file mode 100644 index 00000000..6cac1da8 --- /dev/null +++ b/docs/recipes/developing-and-testing/testing-the-client.md @@ -0,0 +1,144 @@ +# How do I test the client? + +Testing on the client is a little different than on the server. + +This is because the code which is ultimately being executed in the browser is JavaScript, translated from F# by Fable, and so it must be tested in a JavaScript environment. + +Furthermore, code that is shared between the Client and Server must be tested in both a dotnet environment _and_ a JavaScript environment. + +The SAFE template uses a library called Fable.Mocha which allows us to run the same tests in both environments. It mirrors the Expecto API and works in much the same way. + +## **I'm using the standard template** +**** +If you are using the standard template then there is nothing more you need to do in order to start testing your Client. + +In the tests/Client folder, there is a project named `Client.Tests` with a single script demonstrating how to use Mocha to test the TODO sample. + +>Note the compiler directive here which makes sure that the Shared tests are only included when executing in a JavaScript (Fable) context. They are covered by Expecto under dotnet as you can see in `Server.Tests.fs`. + +#### 1. Launch the test server + +In order to run the tests, instead of starting your application using +```powershell +dotnet run +``` +you should instead use +```powershell +dotnet run Runtests +``` + +#### 2. View the results + +Once the build is complete and the website is running, navigate to `http://localhost:8081/` in a web browser. You should see a test results page that looks like this: + + + +> This command builds and runs the Server test project too. If you want to run the Client tests alone, you can simply launch the test server using `npm run test:live`, which executes a command stored in `package.json`. + +## **I'm using the minimal template** + +If you are using the minimal template, you will need to first configure a test project as none are included. + +#### 1. Add a test project +Create a `.Net` library called `Client.Tests` in the `tests/Client` subdirectory using the following commands: + +```powershell +dotnet new classlib -lang F# -n Client.Tests -o tests/Client +dotnet sln add tests/Client +``` + +#### 2. Reference the Client project +Reference the Client project from the Client.Tests project: + +```powershell +dotnet add tests/Client reference src/Client +``` + +#### 3. Add the Fable.Mocha package to Test project +Run the following command: + +```powershell +dotnet add tests/Client package Fable.Mocha +``` + +#### 4. Add something to test + +Add this function to Client.fs in the Client project + +```fsharp +let sayHello name = $"Hello {name}" +``` + +#### 5. Add a test +Replace the contents of `tests/Client/Library.fs` with the following code: + +```fsharp +module Tests + +open Fable.Mocha + +let client = testList "Client" [ + testCase "Hello received" <| fun _ -> + let hello = Client.sayHello "SAFE V3" + + Expect.equal hello "Hello SAFE V3" "Unexpected greeting" +] + +let all = + testList "All" + [ + client + ] + +[] +let main _ = Mocha.runTests all +``` + +#### 6. Add Test web page + +Add a file called `index.html` to the tests/Client folder with following contents: +```html + + + + SAFE Client Tests + + + + + +``` + +#### 7. Add test webpack config + +Add a file called `vite.config.mts` to the root directory with the following contents: + +``` +import { defineConfig } from "vite"; + +// https://vitejs.dev/config/ +export default defineConfig({ + server: { + port: 8081 + } +}); + +``` + +#### 8. Install the client's dependencies + +```powershell +npm install +``` + +#### 9. Launch the test website + +```powershell +cd tests/Client +dotnet fable watch -o output --run npx vite +``` + + +Once the build is complete and the website is running, navigate to `http://localhost:8081/` in a web browser. You should see a test results page that looks like this: + + \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index e26c1472..d82520f6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -75,6 +75,8 @@ nav: - Create a docker image: "recipes/build/docker-image.md" - Remove FAKE: "recipes/build/remove-fake.md" - Package my SAFE app for deployment: "recipes/build/bundle-app.md" + - Dev / Test: + - Test the Client: "recipes/developing-and-testing/testing-the-client.md" - UI: - Add Tailwind support: "recipes/ui/add-tailwind.md" - Add daisyUI support: "recipes/ui/add-daisyui.md" @@ -157,4 +159,4 @@ nav: - Add a NuGet package to the Server: "v4-recipes/package-management/add-nuget-package-to-server.md" - Migrate to Paket from NuGet: "v4-recipes/package-management/migrate-to-paket.md" - Migrate to NuGet from Paket: "v4-recipes/package-management/migrate-to-nuget.md" - - Sync NuGet and NPM Packages: "v4-recipes/package-management/sync-nuget-and-npm-packages.md" + - Sync NuGet and NPM Packages: "v4-recipes/package-management/sync-nuget-and-npm-packages.md" \ No newline at end of file From 3c2037b2942f04e41fa3602c4d145bd1552eca38 Mon Sep 17 00:00:00 2001 From: Joost Date: Wed, 20 Dec 2023 15:57:13 +0000 Subject: [PATCH 2/2] Fix wrong title and wrong path in vite Config step of testing-the-client.md --- docs/recipes/developing-and-testing/testing-the-client.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/recipes/developing-and-testing/testing-the-client.md b/docs/recipes/developing-and-testing/testing-the-client.md index 6cac1da8..62f2d699 100644 --- a/docs/recipes/developing-and-testing/testing-the-client.md +++ b/docs/recipes/developing-and-testing/testing-the-client.md @@ -109,9 +109,9 @@ Add a file called `index.html` to the tests/Client folder with following content ``` -#### 7. Add test webpack config +#### 7. Add test Vite config -Add a file called `vite.config.mts` to the root directory with the following contents: +Add a file called `vite.config.mts` to `tests/Client`: ``` import { defineConfig } from "vite";