diff --git a/website/docs/examples/about.md b/website/docs/examples/about.md new file mode 100644 index 0000000..16ef745 --- /dev/null +++ b/website/docs/examples/about.md @@ -0,0 +1,4 @@ +--- +id: about +title: About examples +--- diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md new file mode 100644 index 0000000..2fb43f3 --- /dev/null +++ b/website/docs/getting-started.md @@ -0,0 +1,44 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Getting Started + +## System requirements + +It requires the following minimum versions : + +- Node v18.10.0 or higher +- Angular v15.2.0 or higher + +Check [version compatibility](./reference/version-compatibility) for more details. + +## Installation + +As this library is intended for testing, install it as a development dependency. + + + + +```shell +pnpm install --save-dev ngx-testing-tools +``` +Registry +> https://npm.im/ngx-testing-tools + + + +```shell +yarn install --dev ngx-testing-tools +``` +Registry +> https://yarn.pm/ngx-testing-tools + + + +```shell +npm install --save-dev ngx-testing-tools +``` +Registry +> https://npm.im/ngx-testing-tools + + diff --git a/website/docs/guides/component.md b/website/docs/guides/component.md new file mode 100644 index 0000000..565cd3b --- /dev/null +++ b/website/docs/guides/component.md @@ -0,0 +1,134 @@ +# Component TestBed + +### Usage + +```ts +describe('AppComponent', () => { + const tb = componentTestBed(AppComponent); + + it('should do something', tb(() => { + // ... expectations + })); +}); +``` + +## Options + +```ts +describe('AppComponent', () => { + const tb = componentTestBed(AppComponent, { + // ... options (see below) + }); +}); +``` + +Options : + +[//]: # (@formatter:off) +```ts +{ + imports?: Importation[] = []; + providers?: AnyProvider[] = []; + declarations?: Declaration[] = []; + schemas?: SchemaMetadata[] = []; + // Disables Angular animations with `provideNoopAnimations()`. + noopAnimations?: boolean = true; + // Run component fixture `detectChanges()` before assertion. + startDetectChanges?: boolean = true; + // Useful when you only want to test the logic of the described component. + // If enabled, no template will be rendered and no change detections will be performed. + noTemplate?: boolean = false; + // Enables `HttpTools`. + httpTesting?: boolean = false; + // When enabled, the assertion will end by `HttpTestingController.verify()`. + // Works only when `httpTesting` test bed option is `true`, otherwise has no effect. + verifyHttp?: boolean = true; + // Automatically compiles the custom test bed for each test. + autoCompile?: boolean = true; + // Automatically invokes the "should create" test. + // It checks if the provided `described` instance is truthy. + checkCreate?: boolean = true; +} +``` +[//]: # (@formatter:on) + +#### ComponentTestBed Definitions + +Check common definitions : + +- [tb.import(..)](#importoneormanyimports---basetestbed) +- [tb.provide(..)](#provideoneormanyproviders---basetestbed) +- [tb.declare(..)](#declareoneormanydeclarations---renderertestbed) +- [tb.inject(..)](#injectname-token---basetestbed) +- [tb.setup(..)](#setupaction---jasmineimplementationcallback) +- [tb.compile(..)](#compile---promisevoid) + +#### (assertion, options?) -> jasmine.ImplementationCallback + +Options : + +[//]: # (@formatter:off) +```ts +{ + // Run component fixture `detectChanges()` before assertion. + startDetectChanges?: boolean = true; + // When enabled, the assertion will end by `HttpTestingController.verify()`. + // Works only when `httpTesting` test bed option is `true`, otherwise has no effect. + verifyHttp?: boolean = true; +} +``` +[//]: # (@formatter:on) + +Check examples : [tb(..)](#assertion-options---jasmineimplementationcallback-2). + +Examples : + +```ts +it('should do something', tb(({ component, fixture, injector, action, query }) => { + component.myInput = true; + fixture.detectChanges(); + + const auth = injector.get(AuthService); + + const inner = query.findComponent(InnerComponent); + + action.click('#my-button'); + + // (…) expectations +}, { startDetectChanges: false })); +``` + +```ts +it('should do something', tb(({ component }, done) => { + // (…) expectations + done(); +})); +``` + +```ts +it('should do something', tb(async ({ component }) => { + // (…) async expectations +})); +``` + +#### ComponentTestBed Tools + +#### ComponentTools + +```ts +{ + // The described component fixture. + fixture: ComponentFixture; + // The described component instance. + component: T; + // Enhanced tools to query elements (see below). + query: ComponentQueryTools; + // Enhanced tools to perform action on elements (see below). + action: ComponentActionTools; +} +``` + +Check common tools : + +- [BaseTools](#basetools) +- [HttpTestingTools](#httptestingtools) diff --git a/website/docs/guides/service.md b/website/docs/guides/service.md new file mode 100644 index 0000000..e69de29 diff --git a/website/docs/intro.md b/website/docs/intro.md deleted file mode 100644 index 45e8604..0000000 --- a/website/docs/intro.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Tutorial Intro - -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 18.0 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. diff --git a/website/docs/introduction.md b/website/docs/introduction.md new file mode 100644 index 0000000..8937bb3 --- /dev/null +++ b/website/docs/introduction.md @@ -0,0 +1,53 @@ +# Introduction + +## In a nutshell + +This library aims to **reduce boilerplate** 😎 and **provides high-level tools**️ 🔥 for testing Component, Service, Interceptor and everything else related to the Angular mechanism. + +It makes tests **easier to read** 😌 and **faster to write** ⚡️! + +## Quick examples + +#### Testing Component + +```ts +describe('AppComponent', () => { + const tb = componentTestBed(AppComponent) // 🛠️ Create the test bed which is re-compiled for each test + .inject('prefs', Preferences); // 🖇️ Link a key to an injection for all tests, see below 👇 + + it('should render title', tb(({ component, query }) => { // 🔋 Access enhanced tools for testing components + expect(component.title).toEqual('app-v17'); + const span = query.findElement('.content span'); + expect(span.textContent).toContain('app-v17 app is running!'); + })); + + it('should update preferences on click', tb(({ action, injected: { prefs } }) => { // 🤯 Retrieve injections by autocompletion + expect(prefs.approved).toBeFalse(); + action.click('#my-button'); + expect(prefs.approved).toBeTrue(); + })); +}); +``` + +🫡 (The redundant "should create" test is even called up for you!) + +#### Testing Service + +```ts +describe('AppService', () => { + const tb = serviceTestBed(AppService, { httpTesting: true }); // 🛠️ Create the test bed and enable http testing + + it('should fetch cat fact', tb(({ service, http, rx }, done) => { + const mockRes = { fact: 'string', length: 6 }; + + rx.remind = service.getCatFact().subscribe({ // 🧯 Use rx.remind to auto unsubscribe after the end of the test + next: (res) => { + expect(res).toEqual(mockRes); + done(); + }, + }); + + http.emitSuccessResponse({ url: service.CAT_FACT_URL, body: mockRes }); // 🎭 Fake the http response of the request that matches the url + })); +}); +``` diff --git a/website/docs/reference/api/overview.md b/website/docs/reference/api/overview.md new file mode 100644 index 0000000..e69de29 diff --git a/website/docs/reference/version-compatibility.md b/website/docs/reference/version-compatibility.md new file mode 100644 index 0000000..8256fae --- /dev/null +++ b/website/docs/reference/version-compatibility.md @@ -0,0 +1 @@ +# Version compatibility diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 44e3114..2e478f5 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -1,51 +1,31 @@ -import { themes as prismThemes } from 'prism-react-renderer'; -import type { Config } from '@docusaurus/types'; import type * as Preset from '@docusaurus/preset-classic'; +import type { Config } from '@docusaurus/types'; +import { themes as prismThemes } from 'prism-react-renderer'; -const config: Config = { - title: 'My Site', - tagline: 'Dinosaurs are cool', +export default { + title: 'Angular Testing Tools', + tagline: 'Makes Angular testing easier', favicon: 'img/favicon.ico', - - // Set the production url of your site here - url: 'https://your-docusaurus-site.example.com', - // Set the // pathname under which your site is served - // For GitHub pages deployment, it is often '//' - baseUrl: '/', - - // GitHub pages deployment config. - // If you aren't using GitHub pages, you don't need these. - organizationName: 'facebook', // Usually your GitHub org/user name. - projectName: 'docusaurus', // Usually your repo name. - + url: 'https://remscodes.github.io', + baseUrl: '/ngx-testing-tools/', + organizationName: 'remscodes', + projectName: 'ngx-testing-tools', onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'warn', - - // Even if you don't use internationalization, you can use this field to set - // useful metadata like html lang. For example, if your site is Chinese, you - // may want to replace "en" with "zh-Hans". - i18n: { - defaultLocale: 'en', - locales: ['en'], - }, - presets: [ [ 'classic', { docs: { + showLastUpdateTime: true, sidebarPath: './sidebars.ts', - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - editUrl: - 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', + path: './docs', + editUrl: 'https://github.com/remscodes/ngx-testing-tools/website', }, blog: { + path: './blog', showReadingTime: true, - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - editUrl: - 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', + editUrl: 'https://github.com/remscodes/ngx-testing-tools/website', }, theme: { customCss: './src/css/custom.css', @@ -53,26 +33,48 @@ const config: Config = { } satisfies Preset.Options, ], ], - + i18n: { + defaultLocale: 'en', + locales: ['en', 'fr'], + }, themeConfig: { // Replace with your project's social card image: 'img/docusaurus-social-card.jpg', navbar: { - title: 'My Site', + title: 'Testing Tools', logo: { - alt: 'My Site Logo', + alt: 'My logo', src: 'img/logo.svg', }, items: [ { + to: '/docs', + label: 'Docs', + type: 'docSidebar', + sidebarId: 'docs', + position: 'left', + }, + { + to: '/examples', + label: 'Examples', type: 'docSidebar', - sidebarId: 'tutorialSidebar', + sidebarId: 'examples', position: 'left', - label: 'Tutorial', }, - { to: '/blog', label: 'Blog', position: 'left' }, { - href: 'https://github.com/facebook/docusaurus', + to: '/reference', + label: 'Reference', + type: 'docSidebar', + sidebarId: 'reference', + position: 'left', + }, + { + to: '/blog', + label: 'Blog', + position: 'right', + }, + { + href: 'https://github.com/remscodes/ngx-testing-tools', label: 'GitHub', position: 'right', }, @@ -85,22 +87,22 @@ const config: Config = { title: 'Docs', items: [ { - label: 'Tutorial', - to: '/docs/intro', + label: 'Getting started', + to: '/docs/introduction', + }, + { + label: 'Examples', + to: '/docs/examples/about', + }, + { + label: 'Reference', + to: '/docs/reference/api/overview', }, ], }, { title: 'Community', items: [ - { - label: 'Stack Overflow', - href: 'https://stackoverflow.com/questions/tagged/docusaurus', - }, - { - label: 'Discord', - href: 'https://discordapp.com/invite/docusaurus', - }, { label: 'Twitter', href: 'https://twitter.com/docusaurus', @@ -116,18 +118,16 @@ const config: Config = { }, { label: 'GitHub', - href: 'https://github.com/facebook/docusaurus', + href: 'https://github.com/remscodes/ngx-testing-tools', }, ], }, ], - copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, + copyright: `Copyright © 2023-${new Date().getFullYear()} Rémy Abitbol`, }, prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, }, } satisfies Preset.ThemeConfig, -}; - -export default config; +} satisfies Config; diff --git a/website/sidebars.ts b/website/sidebars.ts index acc7685..17f6c5e 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -1,31 +1,29 @@ -import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; +import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; -/** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. - */ -const sidebars: SidebarsConfig = { - // By default, Docusaurus generates a sidebar from the docs folder structure - tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], - - // But you can create a sidebar manually - /* - tutorialSidebar: [ - 'intro', - 'hello', +export default { + docs: [ + 'introduction', + 'getting-started', { type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], + label: 'Guides', + collapsed: false, + items: [ + 'guides/component', + ], }, ], - */ -}; - -export default sidebars; + examples: [ + 'examples/about', + ], + reference: [ + { + type: 'category', + label: 'API Reference', + items: [ + 'reference/api/overview', + ], + }, + 'reference/version-compatibility' + ], +} satisfies SidebarsConfig; diff --git a/website/src/pages/index.tsx b/website/src/pages/index.tsx index 400a3e1..bced52b 100644 --- a/website/src/pages/index.tsx +++ b/website/src/pages/index.tsx @@ -1,26 +1,30 @@ -import clsx from 'clsx'; import Link from '@docusaurus/Link'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; -import Layout from '@theme/Layout'; import HomepageFeatures from '@site/src/components/HomepageFeatures'; import Heading from '@theme/Heading'; +import Layout from '@theme/Layout'; +import clsx from 'clsx'; import styles from './index.module.css'; function HomepageHeader() { - const {siteConfig} = useDocusaurusContext(); + const { siteConfig } = useDocusaurusContext(); return (
+
- - {siteConfig.title} - + + {siteConfig.title} + + Website under construction ! +

{siteConfig.tagline}

+
- Docusaurus Tutorial - 5min ⏱️ + to="/docs/introduction"> + Read the docs 🤩
@@ -29,14 +33,14 @@ function HomepageHeader() { } export default function Home(): JSX.Element { - const {siteConfig} = useDocusaurusContext(); + const { siteConfig } = useDocusaurusContext(); return ( - +
- + {/**/}
);